Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Single delivery order

How to receive a single delivery order sent by the buyer

Tradecloud sends purchase orders (new or updated) to suppliers when order events are triggered. This page covers receiving orders with a single delivery per order line.

If you prefer to work with delivery schedules (multiple deliveries per order line), please refer to:

Receive an order

Implementation options

Using the webhook API

Use the POST order webhook endpoint.

  • eventName: Contains the order event name

  • singleDeliveryOrderEvent: Contains the actual order event

Using the polling API

Use the POST poll/single-delivery endpoint.

  • order: Contains the actual order in its current state

Order structure

Order header

The order header contains:

  • id (in order) or orderId (in singleDeliveryOrderEvent): 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 statuses, see Order process status.

  • status.logisticsStatus: is the aggregate of all lines statuses, see Order logistics status.

  • version: the Tradecloud order version number.

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

Buyer order

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:

Download a document attached to an order

  • orderType: the order type, one of Purchase, Forecast or RFQ. Default Purchase.

Supplier order

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.

Order status

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

singleDeliveryOrderEvent 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 reason on the line

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

  • statusLine: the order line values representing the current Issued, Confirmed or InProgress status, see Status line.

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

Buyer line

buyerLine contains the buyer order line fields:

  • position: the line position within the purchase order

  • originalPosition: optional position referencing the original order line when the line has been split

  • 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 and prices. Advised is to use the statusLine.deliveryScheduleInclRequests and statusLine.pricesInclRequests fields instead.

  • 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. \n may be used for a new line in the value.

  • notes: are simple custom fields. \n 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:

Download a document attached to an order

Item

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 of measure, passed through as-is. No standard is enforced; UN/ECE Recommendation N°20 is recommended if you want a standard. A typical example is PCE

  • supplierItemNumber: the item code or number as known at the supplier.

Supplier line

supplierLine is an echo of your order line fields as explained in Send order response​.

Status line

lines.statusLine represents the current order line values related to the current Issued, Confirmed or InProgress process status. The InclRequests fields also include the InProgress status and related open buyer or supplier request values.

Single delivery

When using singleDeliveryOrderEvent one single delivery per order line is used:

  • lines.statusLine.scheduledDelivery: the current delivery line, either having Issued or Confirmed values.

  • lines.statusLine.scheduledDeliveryInclRequests: the current delivery line, either having Issued, InProgress requests or Confirmed values.

Scheduled delivery fields

  • lines.statusLine.scheduledDelivery[InclRequests].date: the delivery date of this delivery line. Date has ISO 8601 date yyyy-MM-dd format. See also Standards.

  • lines.statusLine.scheduledDelivery[InclRequests].quantity: the quantity of this delivery line. Quantity has a decimal 1234.56 format with any number of digits.

Scheduled delivery logistics fields

These additional logistics fields are only available in the status line scheduled delivery:

  • lines.statusLine.scheduledDelivery[InclRequests].status: the optional delivery line's Scheduled delivery logistics status.

  • lines.statusLine.scheduledDelivery[InclRequests].etd: The optional logistics Estimated Time of Departure (local date without time zone). Date has ISO 8601 date yyyy-MM-dd format.

  • lines.statusLine.scheduledDelivery[InclRequests].eta: The optional logistics Estimated Time of Arrival (local date without time zone). Date has ISO 8601 date yyyy-MM-dd format.

Prices

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

  • lines.statusLine.pricesInclRequests: the current delivery line, either having Issued, InProgress requests or Confirmed values.

Prices fields

  • lines.statusLine.prices[InclRequests].grossPrice: the gross price. Used together with discountPercentage.

  • lines.statusLine.prices[InclRequests].discountPercentage: the discount percentage. Used together with grossPrice.

  • lines.statusLine.prices[InclRequests].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.statusLine.prices[InclRequests].priceUnitOfMeasureIso: the price unit of measure, passed through as-is. No standard is enforced; UN/ECE Recommendation N°20 is recommended if you want a standard. The purchase unit and price unit may be different.

  • lines.statusLine.prices[InclRequests].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.

Line status

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

Item details

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 N°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

PreviousDownload a document attached to an orderNextSend order response

Last updated