ProductKnowledgeDevelopers
Platform Control
Modify an order (Order Change)

Modify an existing order via Order Change: endpoint, flow and webhook topics.

Need to modify an order after it has been sent? With an Order Change, the buyer can modify an existing order, for example to adjust quantities, add order lines, or replace items. Order Changes are part of the Peppol Advanced Ordering profile.

How does an Order Change work?

An Order Change is essentially a completely new UBL Order document that references the original order. It replaces the previous order entirely. The supplier receives the modified document and can respond with an Order Response (accept, reject, or conditionally accept).

The flow looks like this:

  1. Buyer sends an Order Change referencing the original order
  2. Supplier receives the modification via the OrderChangeReceived webhook
  3. Supplier downloads the modified order and compares it with the original
  4. Supplier sends an Order Response back (AB, AP, CA or RE)
Endpoint (buyer)

The buyer sends an Order Change by uploading a new UBL Order document via the regular endpoint:

POST /api/v1/{partyId}/purchaseOrder/send

The document contains a reference to the original order in the OrderReference element of the UBL file. The PSB automatically recognises that it is a modification.

Receiving as a supplier

Set up a webhook on the OrderChangeReceived topic:

{
  "action": "https://jouw-endpoint.nl/order-changes",
  "topics": ["OrderChangeReceived"],
  "secret": "jouw-geheime-sleutel"
}

Then download the modified document via:

GET /api/v1/{partyId}/salesOrder/{documentId}/download

Tip: Compare the received document with the original order to determine what has changed. The PSB does not offer a diff function; your system must detect the changes itself.

Webhook topics
TopicDirectionWhenOrderChangeSentBuyerModification has been successfully deliveredOrderChangeReceivedSupplierModification has been receivedOrderResponseReceivedBuyerSupplier has responded to the modification
Responding to an Order Change

As a supplier, you respond to an Order Change via the Order Response endpoint, just like with a regular order. The available status codes are the same: AB (received), AP (accepted), CA (conditionally accepted) and RE (rejected).

Frequently asked questions
How does the PSB recognize that my message is an Order Change and not a new order?

You send the modified UBL Order via the same endpoint as a new order: POST /api/v1/{partyId}/purchaseOrder/send. In the UBL document, you place the reference to the original order in the OrderReference element. The PSB uses this to recognize that it is a modification.

Does an Order Change fully replace the previous order?

Yes. An Order Change is a completely new UBL Order document that references the original order and replaces the previous version. The supplier downloads the document and must determine the differences with the earlier document themselves; the PSB does not offer a diff function.

What integration pattern does the supplier follow after `OrderChangeReceived`?

Set up a webhook on OrderChangeReceived, download via GET /api/v1/{partyId}/salesOrder/{documentId}/download and compare with the previous order. Then respond with an Order Response (AB, AP, CA or RE). The buyer tracks progress via, among others, OrderChangeSent and OrderResponseReceived.

View the full API specification at psb.econnect.eu for the exact UBL structure of an Order Change.

View the API documentation

PreviousReceive order
NextCancel order