ProductKnowledgeDevelopers
Platform Control
Send an order via the API

Send a UBL Order via the PSB API: endpoint, profiles, idempotency and status tracking.

With the PSB API, you can send purchase orders to your suppliers via the Peppol network. The process works similarly to sending invoices: you send a UBL Order XML document to the API, and the PSB takes care of validation, routing and delivery.

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

The request contains the UBL Order XML document as the body with content-type application/xml. The {partyId} is the Peppol identifier of the sending organisation (the buyer).

Order profiles

The PSB supports two Peppol order profiles:

ProfileProfileIDUsageOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3One-way order without responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Full order process with response, modifications and cancellations

With Order Only, the buyer sends an order and the process is complete. With Advanced Ordering, the supplier can respond with an Order Response, and the buyer can modify or cancel the order later.

Tip: Use the Advanced Ordering profile if you want the supplier to confirm the order or if you want to be able to modify orders later.

Basic flow
  1. Upload: send the UBL Order XML document to the endpoint
  2. Validation: the PSB validates the document against the XSD schema and business rules
  3. Routing: the PSB looks up how to reach the recipient via SML/SMP
  4. Delivery: the document is delivered via Peppol to the supplier
  5. Status update: you receive an OrderSent webhook with the delivery status
Idempotency

Use the X-EConnect-DocumentId header to prevent duplicate processing:

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

If you send the same documentId again, the API returns 409 Conflict. Always use a UUID/GUID, never an order number.

Error handling

When delivery fails, the PSB automatically applies retries:

  • Up to 8 attempts spread over approximately 35 hours
  • Only for 5xx server errors (temporary errors on the receiving end)
  • An OrderSentRetry event is published for each attempt
  • On permanent failure, you receive an OrderSentError event
ErrorCauseSolutionValidation error (4xx)Document does not comply with the Peppol standardValidate the document using the Validate APIRecipient not foundIdentifier not registered in PeppolCheck via queryRecipientParty whether the supplier can receive orders409 ConflictA document with this documentId has already been processedNo action neededHTTP 500 for large payloadRequest exceeds the 24 MB web server limit (including overhead)Reduce the document or attachments; account for ~33% base64 overhead
Webhook topics

Set up webhooks for the following topics to track the order process:

TopicWhenOrderSentOrder has been successfully deliveredOrderSentRetryDelivery is being retriedOrderSentErrorOrder could not be deliveredOrderResponseReceivedSupplier has responded to the orderOrderChangeReceivedA modification to the order has been receivedOrderCancellationReceivedA cancellation of the order has been received
Response

A successful upload returns 200 OK with the document ID in the PSB. Use this ID to track the order via the API or via webhooks.

Frequently asked questions
When should I choose Order Only and when Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) is a one-way order without any further message flow. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) is required when the supplier needs to respond with an Order Response or when you want to modify or cancel orders later. Choose Advanced if you need that full process.

How do I prevent duplicate processing when sending an order?

Include the X-EConnect-DocumentId header with a unique UUID or GUID. If you reuse the same documentId, the API responds with 409 Conflict. Do not use an order number as an idempotency key, as it is not intended for this mechanism.

What happens with temporary delivery failures and which webhooks do I receive?

For 5xx errors on the receiving end, the PSB automatically retries delivery (up to 8 attempts over approximately 35 hours). You will see OrderSentRetry for each attempt and OrderSentError on permanent failure. On success, you receive OrderSent.

View the full API specification at psb.econnect.eu for all parameters and example payloads.

Try it in the API

PreviousReceive self-billing
NextReceive order