Receive goods

There are two ways to announce the buyer has received goods:

• using the actual delivery, which is preferred over the delivered indicator, as it is more precise regarding partial deliveries.
• using the delivered indicator

Actual delivery history

The delivery history contains the actual physical deliveries. With the actual deliveries versus the planned deliveries, Tradecloud can calculate which goods should still be delivered or are overdue.

The actual delivery history is matched against the planned delivery schedule by date and quantity, not by delivery line position – deliveryHistory.position and deliverySchedule.position do not have to use the same values.

There are three ways to send the delivery history to Tradecloud:

Send the delivery history by updating an order using the /order endpoint

Send the actual delivery schedule by setting the lines.deliveryHistory field when your ERP system supports a delivery schedule natively, and update the order using the Send order endpoint.

Send the actual delivery by setting the lines.actualDelivery field when using the single delivery per order line feature, and update the order using the Send single delivery order endpoint.

Update an existing orderHow to update an existing purchase order as a buyer

Send delivery events using the /api-connector/order/deliveries endpoint

Send delivery events for one or multiple existing order lines using the Send order deliveries events endpoint. This will append the deliveries to the order line’s delivery history.

Caution

Before adding a delivery to an order, the order must have been sent to Tradecloud first.

Caution

The /order/deliveries endpoint is not supported when using the single delivery feature. Let support know when you need this endpoint for single delivery.

Replace the delivery history using the /api-connector/order/deliveryHistory endpoint

Replace the delivery history for one or multiple existing order lines using the Send order delivery history endpoint. Unlike /order/deliveries, which appends deliveries, this endpoint replaces the delivery history per order line with the deliveries in the request.

Only the lines present in the request are affected; lines not included are left untouched. To clear the delivery history of a line, send that line with an empty deliveryHistory array. As with the other methods, the delivery history is matched against the planned delivery schedule by date and quantity.

Caution

Before replacing the delivery history of an order, the order must have been sent to Tradecloud first.

Caution

The /order/deliveryHistory endpoint is not supported when using the single delivery feature. Let support know when you need this endpoint for single delivery.

Delivered indicator

The delivered indicator marks an order or line as delivered, regardless of the actual quantity or date. It is intended for stock items (lineType Item) where your ERP applies delivery tolerances – a quantity received within tolerance is considered sufficiently delivered.

Note

When to use the delivered indicator

• Use it for stock items with delivery tolerances, where a receipt within tolerance counts as delivered. You may set indicators.delivered on top of the actual delivery history for this purpose – the indicator then completes the line even when the reported quantity does not fully match the planned quantity.
• Do not use the delivered indicator outside this tolerance use case. When you can report exact received quantities and dates, the actual delivery history alone is sufficient and preferred, as it is more precise about partial deliveries.

When an order or line is received, it can be marked as delivered by setting indicators.delivered on either order or line level. Unlike the actual delivery history (matched by date and quantity), the delivered indicator is applied by order line or delivery line position. When set on the order line, all its delivery schedule lines become delivered, including delivery schedule lines without a position. A logistics status sent per delivery schedule line (deliverySchedule.status) is matched by position, so delivery schedule lines without a position are not changed by it. When the line has an actual delivery history, a later order update recalculates its delivery schedule line statuses from that history. The line then goes back to logistics status Open, unless the actual delivery history covers its full quantity. To keep the line delivered, set lines.indicators.delivered again in that update; the order level indicators.delivered does not keep a line that is already delivered.

Caution

Single delivery behavior:

When the primary or any related split lines is delivered; the corresponding delivery line will become delivered.

Mark as delivered by updating an order using the /order endpoint

The existing order or line can be marked as delivered by setting indicators.delivered on either order or line level and updating the order using the Send order endpoint:

Update an existing orderHow to update an existing purchase order as a buyer

Note

If you provide a delivered indicator on order level, ONLY the lines provided in this order message will be marked as delivered. A line that is already delivered is not marked again by the order level indicator, so it can go back to Open when the update recalculates it from its actual delivery history; set lines.indicators.delivered on that line to keep it delivered.

If you also provide a delivered indicator on line level, it has precedence over the order level delivered indicator.

Mark as delivered by sending the delivered indicator using the /order/indicators endpoint

The order or line can be marked as delivered by setting indicators.delivered on either order or line level and sending this indicator only, using the Send order indicators endpoint.

Caution

The /order/indicators endpoint is not supported when using the single delivery feature. Let support know when you need this endpoint for single delivery.

Note

If you provide a delivered indicator on order level, ALL the lines in the order will be delivered.

If you also provide a delivered indicator on line level, it has precedence over the order level delivered indicator.