Receive a shipment event
How to receive a shipment event
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.
Choose the appropriate API to receive a shipment event
First choose either the webhook API or the polling API to receive shipment messages:
pageWebhook versus pollingShipmentEvent
eventName
: the event name, currentlyShipmentIssuedBySupplier
,ShipmentApprovedByBuyer
,ShipmentRejectedByBuyer
orShipmentResentByBuyer
.
Event names may be extended by other shipment events in the future.
shipment
: the shipment state, see Shipment statemeta
: the message meta information, see Message meta information
Shipment state
The shipment data:
id
: the Tradecloud shipment identifieridentifiers
: the identifiers related to this shipment, see Shipment identifierstransportMode
: 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 headerbuyerShipment
: the buyer side header part of the shipment, see Buyer shipment headerloadCarriers
: a list of all the load carriers in this shipment, each load carrier containing shipment lines, see Load carrierlines
: a list of all the shipment lines, not loaded in a load carrier, see Shipment linelocations
: the departure and destination locations with arrival and departure date/times, see Shipment locationsstatus
: the shipment statusprocessStatus
: the shipment process status, currentlyIssued
,Approved
orRejected
, and may be extended with other values in the futureprocessStatusReason
: 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
Shipment identifiers
The identifiers related to this shipment:
billOfLadingNumber
: the bill of lading number as provided by the carrierimoNumber
: the IMO ship identification number as provided by the carriercarrierShipmentNumber
: the shipment number as provided by the carriertrackingNumber
: the tracking number as provided by the carrier or courier
Supplier shipment header
The supplier side header of this shipment:
companyId
: the mandatory Tradecloud company identifier of the suppliersupplierParty
: the unique party identifier and scheme, like GLN, of the supplierbuyerAccountNumber
: the buyer account code or number as used by the suppliershipmentNumber
: the related shipment number as known in the supplier's ERP systeminvoiceNumbers
: the related invoice numbers as known in the supplier's ERP systemdocuments
: the supplier documents attached to this shipment, see Documentcontacts
: the supplier contacts related to this shipment, see Contact
Buyer shipment header
The buyer side header of this shipment:
companyId
: the mandatory Tradecloud company identifier of the buyerbuyerParty
: the unique party identifier and scheme, like GLN, of the buyersupplierAccountNumber
: the supplier account code or number as known at the buyerdocuments
: the buyer documents attached to this shipment, see Documentcontacts
: the buyer contacts related to this shipment, see ContactpurchaseOrderTerms
: the purchase order terms as agreed between buyer and supplier, see Purchase order terms
Contact
A contact person related to this shipment:
userId
: the Tradecloud user identifieremail
: the contact email as known in TradecloudfirstName
: the personal name of the contact personlastName
: the family name of the contact personposition
: the business role of the contact person within the companyphoneNumber
the phone number of the contact person
Document
code
: the unique identifier of the document as provided by the supplier or buyerrevision
: the revision of the documentname
: the short name of the documentdescription
: the description of the documenttype
: 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 Tradecloudmeta
: meta information about the shipment documentlastUpdatedAt
: ISO date and time with timezone at which the shipment document was last updated in Tradecloud. A document has been added or changed if thedocument.meta.lastUpdatedAt
is equal to theshipment.meta.lastUpdatedAt
Purchase order terms
The purchase order terms, as agreed between buyer and supplier, related to this shipment:
incotermsCode
: the incoterms code according to ICC Incoterms 2020incoterms
: the incoterms named place (delivery, terminal, port or destination)paymentTermsCode
: the payment terms code as defined in the buyers ERP systempaymentTerms
: the payment terms text as defined in the buyers ERP system
Load carrier
A load carrier containing shipment lines. Either use the container fields or the generic package fields together with lines.
Container fields
When the load carrier is a container:
containerNumber
: the BIC ISO 6346 Container Identification NumbercontainerSizeAndType
: the BIC ISO 6346 Container Size & Type Code
Generic package fields
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
lines
: a list of all the shipment lines, loaded in this load carrier, see Shipment line
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 buyerpurchaseOrderLinePosition
: the mandatory line position in the purchase order as provided by the buyerdeliverySchedulePosition
: the related delivery schedule position in the purchase order line as provided by the buyeritem
: the item that is shipped, see Shipment itemsupplierLine
: the supplier side of the shipment line, see Supplier shipment linemeta
: meta information about the shipment line, see Shipment line meta information
Shipment item
The item (article, goods) that is being shipped:
buyerItemNumber
: the item number as provided by the buyerbuyerItemRevision
: the revision of the item as provided by the buyerbuyerItemName
: the short name of this item as provided by the buyersupplierItemNumber
: the supplier item code or number as provided by the buyer or suppliersupplierItemRevision
: the revision (or version) as provided by the suppliersupplierItemName
: the short name of this item as provided by the supplierpurchaseUnitOfMeasureIso
: the the 3-letter purchase unit according to ISO 80000-1 which applies to this item
Supplier shipment line
The supplier side of the shipment line:
despatchAdviceNumber
: the mandatory unique despatch advice number as provided by the supplierdespatchAdviceLinePosition
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.
Shipment line meta information
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 thelines.meta.lastUpdatedAt
is equal to theshipment.meta.lastUpdatedAt
Shipment locations
The departure and destination locations together with arrival and departure date/times of a shipment:
departure
: the departure location and dates, see Shipment departuredestinations
: one or more destination locations with arrival and departure date/times, see Shipment destination
Shipment departure
A shipment departure location with ETD and ATD dates:
location
: the departure location, see Shipment locationetdDate
: the Estimated Time of Departure of this shipment from this locationatdDate
: the Actual Time of Departure of this shipment from this location
Shipment destination
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 destinationetaStartTime
: the Estimated Time of Arrival period start time of this shipment at this destinationetaEndDate
: the Estimated Time of Arrival period end date of this shipment at this destinationetaEndTime
: the Estimated Time of Arrival period end time of this shipment at this destinationataDate
: the Actual Time of Arrival of this shipment at this destinationetdDate
: the Estimated Time of Departure of this shipment from this locationatdDate
: the Actual Time of Departure of this shipment from this location
Shipment 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 ofidSchema
idScheme
: scheme, providing context to the location identifier, like GLNnames
: one or more location names. It is recommended to provide at least one name.addressLines
: one or more location address linespostalCode
: location postal codecity
: location citycountryCodeIso
: ISO 3166-1 alpha-2 country code
Shipment meta information
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 shipmentdespatchAdviceErpIssueDateTime
: local date and time at which the despatch advice of this shipment was issued in the supplier's ERP system
Message meta information
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 flowcompanyId
: 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
Last updated