| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Inventory (stock)
• Invoicing (account) • Purchase (purchase) • Discuss (mail) |
| Community Apps Dependencies | Show |
| Lines of code | 2253 |
| Technical Name |
grev_od_purchase_trade_logistics |
| License | OPL-1 |
| Website | https://www.grevlin.com |
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Inventory (stock)
• Invoicing (account) • Purchase (purchase) • Discuss (mail) |
| Community Apps Dependencies | Show |
| Lines of code | 2253 |
| Technical Name |
grev_od_purchase_trade_logistics |
| License | OPL-1 |
| Website | https://www.grevlin.com |
🚢 Purchase Trade LogisticsEnd-to-End International Trade and Logistics Management
|
|
|
|
|
|
|
|
|
|
Grevlin Global CorpProfessional Odoo Solutions for International Trade & Procurement |
Purchase Trade Logistics
The Purchase Trade Logistics module provides end-to-end international trade and logistics management for Odoo 19. It covers the complete shipment lifecycle from Port of Loading (POL) to final delivery, including multi-container tracking, HS code classification, customs clearance workflows, commercial invoice splitting, and vendor bill reconciliation — all integrated with Odoo's standard purchase, stock, and accounting modules.
Note
This module depends on :mod:`grev_od_hs_classification` for versioned WCO 2024 HS code data. Install both modules together for full classification support.
Overview
Key Capabilities
- Multi-container shipment tracking — manage BL numbers, container stacks, vessel and carrier details, and departure/arrival dates through a structured POL → POD lifecycle.
- Customs clearance workflow — structured states (Pending → Submitted → Cleared → Rejected), declaration number capture, and a document vault for customs paperwork.
- Versioned HS code classification — WCO 2024 compliant codes linked to products and shipment lines with full audit trail.
- Commercial invoice splitting — split invoices per BL or per container for precise landed-cost allocation, linked directly to Odoo vendor bills.
- Incoterm enforcement — full integration with Odoo's standard account.incoterms model; incoterms enforced on purchase orders and propagated to shipments.
- Port master (UN/LOCODE) — standardised origin and destination port records for consistent trade documentation.
- On-time delivery KPIs — track delivery performance, delay frequency, and customs compliance rates from the OWL logistics dashboard.
Configuration
Initial Setup
- Install the module from :menuselection:`Settings --> Apps`.
- Ensure the following Odoo standard modules are installed:
- purchase
- stock
- account
- Navigate to :menuselection:`Trade Logistics --> Configuration --> Ports` and verify that the UN/LOCODE port master data has been loaded.
- Navigate to :menuselection:`Trade Logistics --> Configuration --> HS Codes` to review or extend the WCO 2024 classification data loaded by grev_od_hs_classification.
Security Groups
The module defines three access levels following the suite-wide three-tier pattern.
Trade Logistics User
Technical name: group_trade_logistics_user
Permissions: create and update shipments, manage shipment lines, create and manage commercial invoices, view and link vendor bills.
Trade Logistics Officer
Technical name: group_trade_logistics_officer
All user permissions plus: approve customs clearance, manage cost allocations, and access KPI reports.
Trade Logistics Manager
Technical name: group_trade_logistics_manager
Full CRUD including delete. Manages port master, HS code configuration, and security group assignments.
Assigning Users
- Go to :menuselection:`Settings --> Users & Companies --> Users`.
- Select the user to configure.
- Under the Trade Logistics section, choose the appropriate role.
- Click :guilabel:`Save`.
Usage
Creating a Shipment
- Navigate to :menuselection:`Trade Logistics --> Shipments`.
- Click :guilabel:`Create`.
- Select the related :guilabel:`Purchase Order` (required).
- Fill in the shipping details:
- :guilabel:`Bill of Lading` — BL reference number
- :guilabel:`Container Number` — container ID
- :guilabel:`Shipping Line` and :guilabel:`Vessel Name`
- :guilabel:`Departure Date` and :guilabel:`Expected Arrival Date`
- :guilabel:`Origin Port` and :guilabel:`Destination Port` (UN/LOCODE)
- :guilabel:`Incoterm`
- Click :guilabel:`Save` or :guilabel:`Confirm` to advance the workflow.
Shipment Workflow
Shipments progress through seven states:
| State | Description |
|---|---|
| Draft | Initial state; shipment details can be freely edited. |
| Confirmed | Details verified and locked. Use :guilabel:`Confirm` button. |
| In Transit | Vessel has departed. Use :guilabel:`In Transit` button. |
| Arrived | Shipment reached destination port. Use :guilabel:`Mark Arrived`. |
| Cleared | Customs clearance completed. Use :guilabel:`Clear Customs` (auto-sets :guilabel:`Clearance Date`). |
| Delivered | Goods at final destination. Use :guilabel:`Deliver`. |
| Cancelled | Shipment cancelled. Available from any non-delivered state. |
Managing Shipment Lines
- Open a shipment record.
- In the :guilabel:`Shipment Lines` tab, click :guilabel:`Add a Line`.
- Select the :guilabel:`Product` and enter :guilabel:`Quantity`.
- Optionally link to a specific :guilabel:`Purchase Order Line` for cost tracing.
Customs Management
- On the shipment form, fill in:
- :guilabel:`HS Code` — select from the WCO 2024 classification master
- :guilabel:`Customs Declaration Number` — official declaration reference
- Track the clearance status:
- pending → submitted → cleared (or rejected)
- Use :guilabel:`Clear Customs` to mark clearance complete and auto-record the date.
Important
The write() override enforces immutability after a shipment reaches Cleared state. Contact a Trade Logistics Manager to correct data entry errors at that stage.
Commercial Invoice Splitting
- Open a shipment and go to the :guilabel:`Commercial Invoices` tab.
- Click :guilabel:`Add a Line`.
- Fill in:
- :guilabel:`Invoice Number`
- :guilabel:`Bill of Lading` reference (for BL-level split)
- :guilabel:`Container Number` (for container-level split)
- :guilabel:`Invoice Date`, :guilabel:`Total Amount`, and :guilabel:`Currency`
- Link to the corresponding Odoo vendor bill via the :guilabel:`Vendor Bills` field on the shipment for automatic cost reconciliation.
Tip
Split at the container level when multiple containers on one BL carry goods for different cost centres or product categories. The module supports both BL-level and container-level splits on the same shipment.
Technical Details
Models
grev.purchase.shipment
Main shipment model.
| Field | Description |
|---|---|
| name | Auto-generated shipment reference (sequence grev.purchase.shipment) |
| purchase_order_id | Related purchase order (required) |
| partner_id | Supplier (computed from PO) |
| state | Workflow state (draft / confirmed / in_transit / arrived / cleared / delivered / cancelled) |
| bill_of_lading | BL number |
| container_number | Container reference |
| incoterm_id | account.incoterms record |
| origin_country_id / destination_country_id | res.country references |
| hs_code | Harmonized System code |
| customs_status | pending / submitted / cleared / rejected |
| clearance_date | Auto-set when :guilabel:`Clear Customs` action runs |
grev.purchase.shipment.line
Line items on a shipment: product_id, quantity, optional purchase_line_id.
grev.purchase.commercial.invoice
Commercial invoice records with BL and container references for split logic. Key fields: name, shipment_id, bill_of_lading, container_number, invoice_date, total_amount, currency_id.
grev.logistics.port
Port master following UN/LOCODE. Key fields: name, code, country_id.
SQL Report Model
grev.purchase.logistics.report — an _auto = False view model backing the OWL dashboard KPIs (on-time delivery rate, delay frequency, customs compliance rate, landed cost per PO).
Integration Points
Purchase Orders
Shipments link to purchase orders via purchase_order_id. Supplier and incoterm data are automatically propagated from the PO to the shipment on creation.
Accounting
Commercial invoices carry currency and amount information. Vendor bills are linked via a Many2many relation for reconciliation. The module never posts accounting entries — it only prepares cost data consumed by grev_od_purchase_landed_cost.
Inventory
Shipment lines reference product.product records. Quantity data aligns with stock moves but does not create them directly — stock receipts remain in Odoo's standard inventory flow.
Soft Integrations
Cross-module calls are wrapped in try/except guards:
- Landed Cost (grev_od_purchase_landed_cost) — receives container-level cost components for total landed cost calculation.
- Trade Inspection (grev_od_purchase_trade_inspection) — inspection results can be linked to a shipment to block the In Transit transition if failed.
Troubleshooting
Common Issues
- Shipment reference shows "New"
- The sequence grev.purchase.shipment is missing or lacks permissions. Navigate to :menuselection:`Settings --> Technical --> Sequences` and verify the sequence exists and the user has access.
- Cannot create a shipment
- Verify the user has the Trade Logistics User group and that a purchase order is selected (required field).
- Customs status not updating
- Use the :guilabel:`Clear Customs` action button. The manual field is read-only after shipment confirmation to maintain the audit trail.
- Vendor bills not visible
- Confirm the bills exist in the accounting module and the user has sufficient accounting access rights (account.group_account_invoice).
- Immutability error on Cleared shipment
- The write() override blocks edits on cleared records. Ask a Trade Logistics Manager to temporarily reset the state if a correction is genuinely required.
See Also
- :doc:`Odoo Purchase Module </applications/inventory_and_mrp/purchase>`
- :doc:`Odoo Accounting Module </applications/finance/accounting>`
- Incoterms 2020 — ICC
- WCO Harmonized System
- UN/LOCODE Code List
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module