TradeLens uses specific language to refer to the different types of events the platform handles.
In this article
TradeLens uses a simple, logical data model with three related classes: Consignments, Transport Equipment and Shipments.
The main purpose of this model is essentially to start and track consignments, transport equipment (containers) and shipments, while managing the IDs and relationships between them.
The TradeLens platform is flexible and allows a consignment to be in multiple transport equipment, along with other consignments. It also allows transport equipment to be part of multiple consignments.
For example, a consignment of shoes from company A could be split among multiple transport equipment. There could also be shoes from company B in the same container as shoes from company A.
A shipment is an identifiable collection of one or more trade items (available to be) transported together from the seller (original consignor/shipper) to the buyer (final/ultimate consignee).
- Can only be destined for one buyer
- Can be made up of some or all trade items from one or more sales orders
- Can only have one customs unique consignment reference
- May form part or all of a consignment
- May be transported in different consignments
Shipments give insights into transport progress, and are a way to track relevant shipment references. They’re TradeLens’ fundamental object for trade aspects. They mirror the consignment, which is the foundational object for transport and logistics.
TradeLens isn’t a purchase order management system. We don’t support detailed cargo management at PO/SKU line level. However, the shipment trade object does support tracking based on PO/SKU reference numbers (and many other types) for a shipment.
This makes the data searchable and TradeLens data compatible with Enterprise Resource Planning and Supply Chain Management platforms.
The shipment trade object provides an object that trade partners, particularly sellers and buyers, can use to share data and documents.
Shipment association with consignment
The logistical movement of traded goods is handled through one or multiple consignments. In the simplest scenario, the shipment is moved by a single consignment. Often, though, a many-to-many relationship exists between shipments and consignments, reflecting how goods are consolidated in Less-than-Container-Load scenarios.
A single shipment can have multiple consignments. A consignment can have multiple sub-consignments (child consignments), and a sub-consignment can have multiple parent consignments. There’s no limit on the number of levels in the consignment hierarchy.
Data sharing with customs authorities
Shipment data, especially certain documents, is relevant for sharing with customs authorities. In the transport (consignment-based) space, TradeLens determines the relevant customs authorities from the transport plan.
This isn’t applicable for shipments, though. Instead, customs authorities are associated with shipments through two attributes:
- originCountry: where the shipment comes from.
- destinationCountry: the shipment’s final destination.
This approach lets shipment parties prepare a full set of documents before sharing them with the relevant authorities.
A consignment represents the link between what is transported and how it’s transported, ie partial, full, or multiple containers.
From the TradeLens platform perspective, a consignment functions as an aggregator for transport equipment. This means some events that are sent to a consignment and are relevant to the containers, will result in the platform sending that event to all of the transport equipment involved in the consignment.
Similarly, subscribing to a consignment will route all the transport equipment events related to that consignment to the subscription endpoint. This allows participants to operate with a commonly shared identifier.
To learn more about subscriptions, including how to subscribe to TradeLens data, check out our Subscriptions Overview guide here
Transport equipment is the physical equipment used to hold, protect or secure cargo for logistics purposes. We refer to shipping containers as transport equipment.
The vast majority of events happen at container level. The TradeLens platform uses transport equipment to track the movement of a container’s goods from one place to another.
Containers are the units being moved.
The term container is generic; along with intermodal shipping containers of all sizes, it covers single-unit cardboard boxes and anything in between.
- The physical container participates in multiple transport equipment operations over time
- Transport equipment can be created before the exact physical container is known
- Consignment or shipment planning happens most often before the physical container is picked from the depot stack
Transport events are designed to communicate the planned operational route, and how it progresses to completion. Each event represents a significant step that has to happen so transport equipment can reach its destination.
- Carrier release
- Customs release
- Terminal release
- Customs hold
Read our guide to planned, estimated and actual events to learn more about transport events.
Generic events are any unplanned events that can happen to a transport equipment or consignment.
Events for document actions are sent to the platform automatically and internally by the document sharing service.
TradeLens uses matching logic to associate incoming events with a consignment, transport equipment or shipment trade object. There are some cases where an event can’t be matched. If this happens, the platform keeps the event in a special area and will be associated with the trade object if further information is received that enables a match.
- If there’s only one consignment with the carrierBookingNumber, and an event specifies a consignment identifier, then the event will be matched with the consignment.
- If there’s more than one consignment with the same carrierBookingNumber (as in a split consignment case), then either the consignmentId, or the carrierBookingNumber and billOfLadingNumber are needed to uniquely identify the consignment.
- If an event specifies a transport equipment identifier and a transport equipment exists that matches the identifier, then the event will be matched.
- If an event specifies a shipment reference (reference and type) and a shipment exists that matches the shipment reference, then the event will be matched.
For an event submitted with a transportEquipmentRef or an equipmentNumber, a carrierBookingNumber can also be specified. The event will only be matched if a transport equipment reference matching the transport equipment identifier exists, and is associated with a consignment that matches the carrierBookingNumber.