Receive a shipment event
How to receive a shipment event
Last updated
How to receive a shipment event
Last updated
Tradecloud will send a shipment event to the buyer when a shipment event has been triggered.
At this moment a shipment event will only be triggered when the supplier issues or updates a despatch advice.
The shipment module is under development. The API and documentation may change.
First choose either the webhook API or the polling API to receive shipment messages:
eventName: the event name, currently ShipmentIssuedBySupplier, ShipmentApprovedByBuyer, ShipmentRejectedByBuyer or ShipmentResentByBuyer.
Event names may be extended by other shipment events in the future.
shipment: the shipment state, see Shipment state
meta: the message meta information, see Message meta information
The shipment data:
id: the Tradecloud shipment identifier
identifiers: the identifiers related to this shipment, see Shipment identifiers
transportMode: the Mode of Transport name used for the delivery of goods. Unece Code List Recommendation 19 is advised for Mode of Transport names.
supplierShipment: the supplier side header of the shipment, see Supplier shipment header
buyerShipment: the buyer side header part of the shipment, see Buyer shipment header
loadCarriers: a list of all the load carriers in this shipment, each load carrier containing shipment lines, see Load carrier
lines: a list of all the shipment lines, not loaded in a load carrier, see Shipment line
locations: the departure and destination locations with arrival and departure date/times, see Shipment locations
status: the shipment status
processStatus: the shipment process status, currently Issued, Approved or Rejected, and may be extended with other values in the future
processStatusReason: the optional reason of the current process status, for example the reason why the shipment is rejected
meta: meta information about the shipment, see Shipment meta information
The identifiers related to this shipment:
billOfLadingNumber: the bill of lading number as provided by the carrier
imoNumber: the IMO ship identification number as provided by the carrier
carrierShipmentNumber: the shipment number as provided by the carrier
trackingNumber: the tracking number as provided by the carrier or courier
The supplier side header of this shipment:
companyId: the mandatory Tradecloud company identifier of the supplier
supplierParty: the unique party identifier and scheme, like GLN, of the supplier
buyerAccountNumber: the buyer account code or number as used by the supplier
shipmentNumber: the related shipment number as known in the supplier's ERP system
invoiceNumbers: the related invoice numbers as known in the supplier's ERP system
documents: the supplier documents attached to this shipment, see Document
contacts: the supplier contacts related to this shipment, see Contact
The buyer side header of this shipment:
companyId: the mandatory Tradecloud company identifier of the buyer
buyerParty: the unique party identifier and scheme, like GLN, of the buyer
supplierAccountNumber: the supplier account code or number as known at the buyer
documents: the buyer documents attached to this shipment, see Document
contacts: the buyer contacts related to this shipment, see Contact
purchaseOrderTerms: the purchase order terms as agreed between buyer and supplier, see Purchase order terms
A contact person related to this shipment:
userId: the Tradecloud user identifier
email: the contact email as known in Tradecloud
firstName: the personal name of the contact person
lastName: the family name of the contact person
position: the business role of the contact person within the company
phoneNumber the phone number of the contact person
code: the unique identifier of the document as provided by the supplier or buyer
revision: the revision of the document
name: the short name of the document
description: the description of the document
type: the type of the document. Eg. General, Invoice, Packing List, etc...
objectId: the object ID as known by the Tradecloud Object Storage, if this document is stored in Tradecloud, see also:
url: the location of the document if is not stored in Tradecloud
meta: meta information about the shipment document
lastUpdatedAt: ISO date and time with timezone at which the shipment document was last updated in Tradecloud. A document has been added or changed if the document.meta.lastUpdatedAt is equal to the shipment.meta.lastUpdatedAt
The purchase order terms, as agreed between buyer and supplier, related to this shipment:
incotermsCode: the incoterms code according to ICC Incoterms 2020
incoterms: the incoterms named place (delivery, terminal, port or destination)
paymentTermsCode: the payment terms code as defined in the buyers ERP system
paymentTerms: the payment terms text as defined in the buyers ERP system
A load carrier containing shipment lines. Either use the container fields or the generic package fields together with lines.
When the load carrier is a container:
containerNumber: the BIC ISO 6346 Container Identification Number
containerSizeAndType: the BIC ISO 6346 Container Size & Type Code
When the load carrier is NOT a container:
packageSSCC: the package GS1 Serial Shipping Container Code (SSCC)
packageType: the package type, Unece Code List Recommendation 21 is advised
lines: a list of all the shipment lines, loaded in this load carrier, see Shipment line
A shipment line containing identifiers, item and supplier data including quantities. A line has been added to either a shipment directly or to a load carrier.
purchaseOrderNumber: the mandatory related purchase order number as provided by the buyer
purchaseOrderLinePosition: the mandatory line position in the purchase order as provided by the buyer
deliverySchedulePosition: the related delivery schedule position in the purchase order line as provided by the buyer
item: the item that is shipped, see Shipment item
supplierLine: the supplier side of the shipment line, see Supplier shipment line
meta: meta information about the shipment line, see Shipment line meta information
The item (article, goods) that is being shipped:
buyerItemNumber: the item number as provided by the buyer
buyerItemRevision: the revision of the item as provided by the buyer
buyerItemName: the short name of this item as provided by the buyer
supplierItemNumber: the supplier item code or number as provided by the buyer or supplier
supplierItemRevision: the revision (or version) as provided by the supplier
supplierItemName: the short name of this item as provided by the supplier
purchaseUnitOfMeasureIso: the the 3-letter purchase unit according to ISO 80000-1 which applies to this item
The supplier side of the shipment line:
despatchAdviceNumber: the mandatory unique despatch advice number as provided by the supplier
despatchAdviceLinePosition the mandatory position in the despatch advice as provided by the supplier. The position is unique within the despatch advice and immutable.
despatchQuantity the mandatory despatch quantity of this purchase order line or delivery schedule position.
backorderQuantity: the backorder quantity of this purchase order line or delivery schedule position.
lastUpdatedAt: ISO date and time with timezone at which the shipment line was last updated in Tradecloud. A line has been added or changed if the lines.meta.lastUpdatedAt is equal to the shipment.meta.lastUpdatedAt
The departure and destination locations together with arrival and departure date/times of a shipment:
departure: the departure location and dates, see Shipment departure
destinations: one or more destination locations with arrival and departure date/times, see Shipment destination
A shipment departure location with ETD and ATD dates:
location: the departure location, see Shipment location
etdDate: the Estimated Time of Departure of this shipment from this location
atdDate: the Actual Time of Departure of this shipment from this location
A shipment place, port or final destination with location, ETA time window, ATA, ETD and ATD dates:
location: the location where the shipment should arrive next, see Shipment location
Estimated start and end date/times indicate the scheduled time window of arrival:
etaStartDate: the Estimated Time of Arrival period start date of this shipment at this destination
etaStartTime: the Estimated Time of Arrival period start time of this shipment at this destination
etaEndDate: the Estimated Time of Arrival period end date of this shipment at this destination
etaEndTime: the Estimated Time of Arrival period end time of this shipment at this destination
ataDate: the Actual Time of Arrival of this shipment at this destination
etdDate: the Estimated Time of Departure of this shipment from this location
atdDate: the Actual Time of Departure of this shipment from this location
locationType: a location type according to ICC Incoterms 2020:
AgreedPlace (used with EXW, FCA)
PortOfLoading (used with FAS, FOB)
PortOfDestination (used with CFR, CIF)
PlaceOfDestination (used with CPT, CIP)
FinalDestination (used with DAP, DPU, DDP)
id: the required identifier for the location, in context of idSchema
idScheme: scheme, providing context to the location identifier, like GLN
names: one or more location names. It is recommended to provide at least one name.
addressLines: one or more location address lines
postalCode: location postal code
city: location city
countryCodeIso: ISO 3166-1 alpha-2 country code
lastUpdatedAt: ISO date and time with timezone at which the shipment was last updated in Tradecloud, useful for polling shipments.
supplierErpMeta the supplier's ERP meta information about this shipment
despatchAdviceErpIssueDateTime: local date and time at which the despatch advice of this shipment was issued in the supplier's ERP system
messageId: the Tradecloud identifier of this message.
source: includes meta information about the source of this message:
traceId: the Tradecloud trace identifier of this message. All related messages in a flow will have the same tradeId.
userId: the Tradecloud user identifier which triggered the first message in a flow
companyId: the Tradecloud company identifier which triggered the first message in a flow
createdDateTime: date and time with time zone, at which this message was created