Receive an order
How to receive a purchase order sent by the buyer.
Last updated
How to receive a purchase order sent by the buyer.
Last updated
Tradecloud will send a purchase order, either new or updated, to the supplier when an order event has been triggered.
You must choose between the webhook API or the polling API to receive order messages:
You must choose between delivery schedule or single delivery per order line:
When choosing the single delivery please continue on:
orderEvent or order headerThis page assumes you either chose the orderEvent webhook API or the order polling API.
id (in case of an order): the Tradecloud order identifier.
orderId (in case of an orderEvent): the Tradecloud order identifier.
buyerOrder: the buyer part of the order, see below.
supplierOrder: the supplier part of the order.
indicators.deliveryOverdue is true when at least one order line is overdue.
status.processStatus: is the aggregate of all lines Order process statuses.
status.logisticsStatus: is the aggregate of all lines Order logistics statuses.
version: the Tradecloud order version number.
eventDates: some key order event date/times.
meta: meta information, including source and trace info, about this messsage.
lastUpdatedAt: is the latest date time the order has been changed, useful for polling orders.
buyerOrder contains the buyer order fields:
companyId: the buyer's Tradecloud company identifier.
supplierAccountNumber: your account number as known in the buyer's ERP system.
description: a free format additional description of this order added by the buyer.
contact: the buyer employee responsible for this order.
properties: are key-value based custom fields, added by the buyer.
notes: are simple custom fields, added by the buyer.
labels: value-added services labels on order level.
documents: contain meta data, objectId or url, of attached documents by the buyer. See:
orderType: the order type, one of Purchase, Forecast or RFQ. Default Purchase.
supplierOrder is mostly an echo of your order fields as explained in Send order response.
buyerAccountNumber: the buyer account number as known in your ERP system.
The buyerAccountNumber should be set on forehand in the Tradecloud connection with your buyer. You can set the account code when inviting a new connection or in the connection overview in the portal.
The order status is the aggregation of all the lines statuses.
The order process status is one of:
Issued: the order is (re)issued by the buyer.
InProgress: the order is under negotiation between buyer and supplier
Confirmed: the order is completely agreed between buyer and supplier
Rejected: the order is completely rejected by supplier
Completed: the order is completed at the buyer
Cancelled: the order is cancelled by the buyer
The order logistics status is one of:
Open: no or partial quantity Produced, ReadyToShip, Shipped or Delivered
Produced: the order full quantity is produced by the supplier
ReadyToShip: the order full quantity is ready to be shipped by the supplier
Shipped: the order full quantity is shipped by the supplier
Delivered: the order full quantity is delivered at the buyer
Cancelled: the order is cancelled by the buyer
orderEvent or order lineslines contains one or more order lines:
id: the Tradecloud line identifier.
buyerLine: the buyer part of the order line, see Buyer line below.
supplierLine: the supplier part of the order line, see Supplier line below.
confirmedLine: the order line as agreed between buyer and supplier, see Confirmed line below.
deliverySchedule: the current aggregated delivery schedule, see Delivery schedule.
deliveryScheduleIncludingRequests: the current aggregated delivery schedule including requests, see Delivery schedule.
prices: the actual prices, see Prices below.
pricesIncludingRequests: the actual prices, including any open supplier or buyer requests, see Prices.
indicators.deliveryOverdue is true when the order line is overdue.
status.processStatus: the order line's Line process status.
status.inProgressStatus the order line's Line in progress status.
status.logisticsStatus: the order line's Line logistics status.
eventDates: some key line event date/times.
mergedItemDetails: detailed part information provided by both buyer and supplier, see Item details.
lastUpdatedAt: is the latest date time the order line has been changed, useful for polling.
buyerLine contains the buyer order line fields:
position: the line position within the purchase order
description: a free format additional description of this line
item: the item (or article, goods) to be delivered, see Item
requests: the buyer can request different delivery schedule, prices and charge lines
terms: the line terms as agreed with your buyer
contractNumber: the agreed framework contract number
contractPosition: the related position within the framework contract
projectNumber: The buyer's project number reference
productionNumber: The buyer's production number reference
salesOrderNumber: The buyer's sales order number (not be confused with your sales order number)
indicators.noDeliveryExpected: No goods are expected to be delivered to the buyer, for example a service, fee or text line.
indicators.delivered: All goods are delivered at the buyer.
properties: are key-value based custom fields. may be used for a new line in the value.
notes: are simple custom fields. may be used for a new line.
labels: value-added services labels on line level.
documents: contain meta data and link of attached documents, see:
lines.buyerLine.item: The item (or article, goods) to be delivered.
number: the item code or number as known in the buyer ERP system.
revision: the revision (or version) of this item number
name: the item short name
purchaseUnitOfMeasureIso: the purchase unit according to ISO 80000-1, a typical example is PCE
supplierItemNumber: the item code or number as known at the supplier.
lines.buyerLine.requests.reopenRequest: the buyer requests to reopen the confirmed order line. The buyer has requested a different delivery schedule, prices and/or charge lines compared to the confirmed order line.
deliverySchedule: the requested alternative delivery schedule
prices: the requested alternative prices
chargeLines: the requested alternative charge lines, see Charge lines
reason: the reason of this request given by the supplier
status: the Request status.
Request status
The request status is one of:
Open: Requested by one party. To be approved or rejected by the other party.
Approved: The request is approved by the other party.
Rejected: The request is rejected by the other party.
Closed: The request is closed because it is not relevant anymore.
If the request status is Open the other party must approve or reject it.
supplierLine is an echo of your order line fields as explained in Send order response.
lines.confirmedLine: the agreed order line between buyer and supplier.
Only if the process status is Confirmed the line is agreed between buyer and supplier
lines.confirmedLine.deliverySchedule: the agreed delivery schedule
lines.confirmedLine.prices: the agreed prices
lines.confirmedLine.chargeLines: the agreed charge lines, see Charge lines
When using order or orderEvent the delivery schedule is used.
The lines.deliverySchedule together with the lines.prices fields give a simpler alternative for the deliverySchedule and prices fields in different places like buyerLine, buyerLine.requests, supplierLine.requests and confirmedLine.
lines.deliverySchedule: the current delivery schedule, either having Issued or Confirmed values.
The lines.deliverySchedule field does NOT include any open supplier or buyer request. Be aware that either the Issued or Confirmed values are returned, dependent on the line status.
lines.deliveryScheduleIncludingRequests: the current delivery schedule, either having Issued, In Progress or Confirmed values.
The lines.deliveryScheduleIncludingRequests field does include any open supplier or buyer request. Be aware that the Issued, proposal or reopen request or Confirmed values are returned, dependent on the line and request status.
lines.deliverySchedule[IncludingRequests].position: the optional position in the delivery schedule. Not to be confused with the line.position
lines.deliverySchedule[IncludingRequests].date: the delivery date of this delivery schedule position. Date has ISO 8601 date yyyy-MM-dd format. See also Standards.
lines.deliverySchedule[IncludingRequests].quantity: the quantity of this delivery schedule position. Quantity has a decimal 1234.56 format with any number of digits.
Logistics fields
These additional logistics fields are only available in the order line level delivery schedule:
lines.deliverySchedule[IncludingRequests].status: the optional delivery line's Scheduled delivery logistics status.
lines.deliverySchedule[IncludingRequests].etd: The optional logistics Estimated Time of Departure (local date without time zone). Date has ISO 8601 date yyyy-MM-dd format.
lines.deliverySchedule[IncludingRequests].eta: The optional logistics Estimated Time of Arrival (local date without time zone). Date has ISO 8601 date yyyy-MM-dd format.
Scheduled delivery logistics status
The delivery line logistics status is one of:
Open: no or partial quantity Produced, ReadyToShip, Shipped or Delivered
Produced: the delivery line quantity is produced by the supplier
ReadyToShip: the delivery line quantity is ready to be shipped by the supplier
Shipped: the delivery line quantity is shipped by the supplier
Delivered: the delivery line quantity is delivered at the buyer
lines.prices: the current prices, either having Issued or Confirmed values.
The lines.prices field does NOT include any open supplier or buyer request. Be aware that either the Issued or Confirmed values are returned, dependent on the line status.
lines.pricesIncludingRequests: the current prices, either having Issued, In Progress or Confirmed values.
The lines.pricesIncludingRequests field includes any open supplier or buyer request. Be aware that the Issued, proposal or reopen request or Confirmed values are returned, dependent on the line and request status.
lines.prices[IncludingRequests].grossPrice: the gross price. Used together with discountPercentage.
lines.prices[IncludingRequests].discountPercentage: the discount percentage. Used together with grossPrice.
lines.prices[IncludingRequests].netPrice: the net price.
priceInTransactionCurrency: the price in the transaction currency of the supplier, like CNY in China.
value: the price value has a decimal 1234.56 format with any number of digits.
currencyIso: the 3-letter currency code according to ISO 4217, like EUR, USD and CNY
priceInBaseCurrency: the price in your base currency, like EUR in the EU.
value: the price value has a decimal 1234.56 format with any number of digits.
currencyIso: the 3-letter currency code according to ISO 4217, like EUR.
lines.prices[IncludingRequests].priceUnitOfMeasureIso: the 3-letter price unit according to ISO 80000-1. The purchase unit and price unit may be different.
lines.prices[IncludingRequests].priceUnitQuantity: the item quantity at which the price applies. Typically this is 1 (unit price) or 100 (the price applies to 100 items)
It is advised to only use netPrice for its simplicity, or alternatively use grossPrice together with discountPercentage.
The line process status is one of:
Issued: the line is (re)issued by the buyer
InProgress: the line is under negotiation between buyer and supplier
Confirmed: the line is agreed between buyer and supplier
Rejected: the line is rejected by supplier
Completed: the line is completed at the buyer
Cancelled: the line is cancelled by the buyer
The line in progress status is a more fine-grained status when an order line processStatus is InProgress and is one of:
OpenSupplierProposal: There is an open proposal from the supplier.
RejectedSupplierProposal: The proposal from the supplier was rejected and no other requests are open.
ReissuedRejectedLine: The rejected order line was reissued by the buyer.
OpenSupplierReopenRequest: There is an open reopen request from the supplier.
OpenBuyerReopenRequest: There is an open reopen request from the buyer.
RevertedCompletedLine: The completion of this line was reverted.
The line logistics status is one of:
Open: no or partial quantity Produced, ReadyToShip, Shipped or Delivered
Produced: the line quantity is produced by the supplier
ReadyToShip: the line quantity is ready to be shipped by the supplier
Shipped: the line quantity is shipped by the supplier
Delivered: the line quantity is delivered at the buyer
Cancelled: the line is cancelled by the buyer
chargeLines: the requested or confirmed additional cost lines of an order line, independent of the order line prices, like transport, packing, administration, inspection and certification costs.
position: the position used to identify a charge line.
chargeTypeCode: the mandatory charge reason code according to UNCL7161
chargeDescription: a mandatory free text description, like "Transport costs".
quantity: the mandatory quantity of this charge line.
price: the mandatory price of this charge line.
priceInTransactionCurrency: the mandatory price in the transaction currency of the supplier, like CNY in China.
value: the price value has a decimal 1234.56 format with any number of digits.
currencyIso: the 3-letter currency code according to ISO 4217, like EUR, USD and CNY.
priceInBaseCurrency: the optional price in your base currency, like EUR in the EU.
value: the price value has a decimal 1234.56 format with any number of digits.
currencyIso: the 3-letter currency code according to ISO 4217, like EUR.
priceUnitOfMeasureIso: the 3-letter price unit according to ISO 80000-1 which applies to the charge line price.
The buyer may send item details to inform the supplier about part information.
The supplier may check, change and add item details if they are not correct or incomplete.
lines.mergedItemDetails will contain the original item details added by the buyer merged with the changed or added item details by the supplier.
countryOfOriginCodeIso2: The ISO 3166-1 alpha-2 country code of manufacture, production, or growth where an article or product comes from.
combinedNomenclatureCode: A tool for classifying goods, set up to meet the requirements both of the Common Customs Tariff and of the EU's external trade statistics.
netWeight: Net weight of one item.
netWeightUnitOfMeasureIso: Net weight unit according to ISO 80000-1.
dangerousGoodsCodeUnece: UN numbers or UN IDs are four-digit numbers that identify dangerous goods, hazardous substances and articles in the framework of international transport.
serialNumber: is an unique identifier assigned incrementally or sequentially to an item, to uniquely identify it.
batchNumber: is an identification number assigned to a particular quantity or lot of material from a single manufacturer