Receive an order response

Tradecloud sends purchase order responses to buyers when order events are triggered.

Receiving methods

Choose your API method

You must choose between two methods to receive order responses:

• Webhook API (Push): Tradecloud pushes order events to your system.
• Polling API (Pull): Your system periodically checks for order updates.

For details on choosing between these methods:

Webhook versus pollingChoose between the webhook or polling APIs to receive an order, order response or shipment message

Choose your delivery format

You must also choose between two delivery formats:

• Delivery schedule: Multiple scheduled deliveries per order line
• Single delivery: One scheduled delivery per order line

For details on choosing between these formats:

Delivery schedule versus single deliveryChoose between delivery schedule or single delivery per order line.

If you’re using single delivery format, please see:

Receive a single delivery order responseHow to receive a single delivery order response sent by the supplier

Implementation options

Using the webhook API

See the Webhook setup guide for instructions on how to configure the webhook API.

Use the POST order webhook endpoint.

The webhook body contains:

• eventName: Contains the Order event name
• orderEvent: Contains the actual order event
• meta: The message meta information, see Message meta information

Using the polling API

See the Polling setup guide for instructions on how to configure polling.

Use the POST poll orders endpoint.

The polling response body contains:

• data: Contains the actual orders in its current state
• total: The total no. of matching orders, regardless of paging.
• lastUpdatedAt: Store the lastUpdatedAt value to use as lastUpdatedAfter in subsequent requests.

Response structure

This section assumes you’re using delivery schedules with either the orderEvent webhook API or the order polling API.

Order header

The order header contains:

• id (in order) or orderId (in orderEvent): Tradecloud order identifier
• buyerOrder: the buyer part of the order, see Buyer order
• supplierOrder: the supplier part of the order, see Supplier order
• indicators.deliveryOverdue is true when at least one order line is overdue.
• status.processStatus: is the aggregate of all lines Order process status.
• status.logisticsStatus: is the aggregate of all lines Order logistics status.
• version: the Tradecloud order version number, see Order version.
• eventDates: some key order event date/times
• meta: meta information, including source and trace info, about this message
• lastUpdatedAt: is the latest date time the order has been changed, useful for polling orders.

Buyer order

buyerOrder is mostly an echo of your order fields as explained in Issue a new order

• supplierAccountNumber: the supplier account number as known in your ERP system

Supplier order

supplierOrder contains the supplier order fields:

• companyId: the supplier’s Tradecloud company identifier.
• buyerAccountNumber: your account number as known in the supplier’s ERP system.
• description: a free-format additional description of this order by the supplier.
• contact: the supplier employee responsible for this order.
• properties: are key-value-based custom fields, added by the supplier.
• notes: are simple custom fields, added by the supplier.
• documents: contain meta data and link of attached documents by the supplier.
  • meta: optional meta information about the document, set by Tradecloud
    • addedAt: ISO date and time with timezone when the document was first added to the order, whether sent with the order or attached separately. Not present for documents added before this field was introduced.
    • lastUpdatedAt: ISO date and time with timezone when the document was last sent again with changed values. Not bumped when sent again with identical values, so it equals addedAt for a document that has never changed. Not present for documents added before this field was introduced.

Download a document attached to an order responseHow to download a document from an order or line response

Order status

The order status is the aggregation of all the lines statuses. See Order status for the complete list of values.

orderEvent or order lines

lines contains one or more order lines:

• id: the Tradecloud line identifier
• lineType: one of Item, Service, or Charge. See Order line type
• chargeReasonCode: optional UNCL7161 code when the buyer set a charge
• buyerLine: the buyer part of the order line, see Buyer line.
• supplierLine: the supplier part of the order line, see Supplier line.
• confirmedLine: the order line as agreed between buyer and supplier, see Confirmed line.
• deliverySchedule: the current aggregated delivery schedule, see Delivery schedule.
• deliveryScheduleIncludingRequests: the current aggregated delivery schedule including requests, see Delivery schedule.
• prices: the current prices, see Prices below.
• pricesIncludingRequests: the current 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.

Buyer line

lines.buyerLine is an echo of your order line fields as explained in Issue a new order

• position: the line position within the purchase order

Supplier line

lines.supplierLine contains the supplier order line fields:

• salesOrderNumber: the sales order number as known in the supplier’s ERP system
• salesOrderPosition: the position within the supplier’s sales order
• description: a free-format additional description of this line by the supplier
• requests: the supplier can request different delivery schedule and prices, see below
• properties: are key-value-based custom fields, added by the supplier
• notes: are simple custom fields, added by the supplier
• documents: contain meta data, objectId or url, of attached documents by the supplier.
  • meta: optional meta information about the document, set by Tradecloud
    • addedAt: ISO date and time with timezone when the document was first added to the order line, whether sent with the order or attached separately. Not present for documents added before this field was introduced.
    • lastUpdatedAt: ISO date and time with timezone when the document was last sent again with changed values. Not bumped when sent again with identical values, so it equals addedAt for a document that has never changed. Not present for documents added before this field was introduced.

Download a document attached to an order responseHow to download a document from an order or line response

Supplier requests

lines.supplierLine.requests.proposal: the supplier has proposed a different delivery schedule and prices compared to the issued order line. lines.supplierLine.requests.reopenRequest: the supplier requests to reopen the confirmed order line. The supplier has requested a different delivery schedule and prices compared to the confirmed order line.

• deliverySchedule: the requested alternative delivery schedule
• prices: the requested alternative prices
• chargeLines (deprecated): the requested alternative charge lines, see Charge lines
• reason: the reason of this request given by the supplier
• status: the Request status.

Confirmed line

lines.confirmedLine: the agreed order line between buyer and supplier.

Caution

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 (deprecated): the agreed charge lines, see Charge lines

Delivery schedule

When using order or orderEvent the delivery schedule is used.

Note

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.

Caution

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.

Caution

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.

Delivery schedule fields

• 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.

See Scheduled delivery logistics status for the complete list of values.

Prices

• lines.prices: the current prices, either having Issued or Confirmed values.

Caution

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.

Caution

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.

Prices fields

• 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 price unit of measure, passed through as-is. No standard is enforced; UN/ECE Recommendation No. 20 is recommended if you want a standard. 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)

Note

It is advised to only use netPrice for its simplicity, or alternatively use grossPrice together with discountPercentage.

Line status

See Line status for the complete list of line process, in progress and logistics status values.

Charge lines

Caution

Deprecated. Charge lines (chargeLines) are deprecated. Superseded by lineType Charge and line-level pricing, see Order line type.

Item details

Note

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 of measure, passed through as-is. Mandatory when netWeight is provided. No standard is enforced; UN/ECE Recommendation No. 20 is recommended if you want a standard.
• 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

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 traceId
  • 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 when this message was created