Order-X Creation API Reference
Technical reference for generating Order-X hybrid purchase orders from a structured JSON request. Order-X is the order companion of Factur-X and ZUGFeRD, published jointly by FNFE-MPE and FeRD: a readable PDF/A-3 carrying a UN/CEFACT Cross-Industry Order XML attached as order-x.xml. Submit buyer, seller and the ordered line items, totals are calculated automatically, and the XML is validated against the official Order-X 1.0 schema and business rules before the PDF is assembled.
Two ways to get a compliant purchase order
Let InvoiceXML design the document from your data, or keep your own PDF layout and have us make it Order-X compliant. Either way you get back a valid PDF/A-3 with the structured order XML embedded.
We generate the PDF
Send only your order data and the API renders a clean purchase-order PDF for you. Tune the look with options.brandColor and options.language.
Bring your own PDF
Already have a designed order PDF? Pass its public URL as options.pdfUrl and we embed the compliant Order-X XML into it, keeping your exact layout, fonts, and branding.
https://api.invoicexml.com/v1/create/order-x
Example request
curl -X POST https://api.invoicexml.com/v1/create/order-x \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-o order-order-x.pdf \
-d '{
"order": {
"invoiceNumber": "PO-2026-00021",
"issueDate": "2026-07-12",
"currency": "EUR",
"buyer": {
"name": "Globex SAS",
"postalAddress": { "line1": "15 rue de Rivoli", "city": "Paris", "postCode": "75001", "country": "FR" }
},
"seller": {
"name": "Acme Engineering GmbH",
"vatIdentifier": "DE123456789",
"postalAddress": { "line1": "Hauptstrasse 12", "city": "Berlin", "postCode": "10115", "country": "DE" }
},
"delivery": { "actualDeliveryDate": "2026-08-01" },
"lines": [
{
"quantity": 10,
"unitCode": "C62",
"priceDetails": { "netPrice": 150.00 },
"vatInformation": { "categoryCode": "S", "rate": 19.0 },
"item": { "name": "Hydraulic valve V-220" }
}
]
},
"options": { "profile": "comfort", "typeCode": "220", "language": "de" }
}'
The document number field (invoiceNumber) carries the order number, and
delivery.actualDeliveryDate becomes the order's requested delivery event.
Request body
The envelope is { "order": { ... }, "options": { ... } }. The
order object uses the same BT-first document model as the invoice
creation endpoints (parties, line items, references, totals), documented field by field in the
Factur-X creation reference.
Totals and the tax breakdown are calculated automatically when omitted. Invoice-only fields
(paymentDetails, dueDate,
typeCode) are ignored on orders.
| Option | Type | Description |
|---|---|---|
| options.profile | string | Order-X conformance profile: basic, comfort (default), or extended. Decides the guideline identifier stamped into the XML and the Order-X 1.0 rule set the document is validated against. |
| options.typeCode | string | UNTDID 1001 document type: 220 order (default), 230 order change, or 231 order response. |
| options.language | string | Localisation of the rendered PDF template: en (default), de, or fr. Ignored when pdfUrl supplies the visual layer. |
| options.brandColor | string | Primary brand colour of the rendered PDF template, hex #RRGGBB. Ignored when pdfUrl is set. |
| options.pdfUrl | string | Absolute http(s) URL of your own PDF to use as the visual layer. The API fetches it (with size, content-type and SSRF protections) and embeds the generated order XML into it. |
Headers
| Header | Value |
|---|---|
| Authorization * | Bearer YOUR_API_KEY |
| Content-Type | application/json |
Response
200 Generated Order-X PDF
The purchase order was generated and validated. The response body is the hybrid PDF/A-3 with the embedded order-x.xml, returned as a binary download.
400 Validation error
Model validation failures (errorCode 4002) and Order-X rule violations in the generated XML (errorCode 4001) both return RFC 7807 ProblemDetails with structured findings. Error field paths are rooted at the order envelope.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "XML Validation Failed",
"status": 400,
"errorCode": 4001,
"detail": "The generated order contains 1 validation error(s).",
"errors": [
{
"rule": "XSD",
"line": null,
"message": "The required attribute 'mimeCode' is missing.",
"btCodes": [],
"fields": [],
"raw": "[XSD] XSD: The required attribute 'mimeCode' is missing. (at ram:AttachmentBinaryObject)"
}
],
"warnings": []
}
Need the raw order XML instead?
POST /v1/create/cio accepts the identical request body and returns the validated Cross-Industry Order XML on its own, without the PDF wrapper.
Frequently Asked Questions
What is Order-X?
Order-X is the standard for hybrid electronic purchase orders from FNFE-MPE and FeRD, the same organisations behind Factur-X and ZUGFeRD. Like those invoice formats, an Order-X file is a PDF/A-3 the recipient can read, with a structured UN/CEFACT Cross-Industry Order (CIO) XML embedded for machine processing. Unlike the invoice standard, Order-X carries one name in both France and Germany.
How does the request body relate to the invoice /create endpoints?
It is the same BT-first document model under a different envelope key: { "order": { ... }, "options": { ... } } instead of { "invoice": ... }. Parties, line items, references and totals are expressed identically, so an integration that already builds invoice payloads reuses its mapping. Invoice-only fields (payment details, due date, invoice type code) are ignored; the order type comes from options.typeCode instead.
Which Order-X profiles can I generate?
Set options.profile to basic, comfort, or extended; the default is comfort, the sensible middle profile for standard purchase orders. The profile decides both the guideline identifier stamped into the XML (urn:order-x.eu:1p0:comfort and siblings) and the Order-X 1.0 rule set the document is validated against before delivery.
What does options.typeCode control?
The UNTDID 1001 document type of the order: 220 for an order (the default), 230 for an order change, and 231 for an order response. The code is written into the CIO's ExchangedDocument type code, which is how receiving systems distinguish a new order from a change to or answer on an existing one.
Can I use my own PDF as the visual layer?
Yes, exactly like the invoice endpoints. Set options.pdfUrl to an absolute http(s) URL of your PDF and the API downloads it (with size, content-type and SSRF protections) and embeds the generated order XML into it. Without pdfUrl the API renders its own purchase-order template, localized via options.language (en, de, fr) and branded via options.brandColor (hex #RRGGBB).
Is the output validated automatically?
Yes. The generated Cross-Industry Order is validated against the official Order-X 1.0 schema and business rules for the selected profile before the PDF is assembled. Orders are not EN 16931 documents, so the invoice rule sets do not apply here; if validation fails, the API returns a 400 response with errorCode 4001 and the violated rules as findings.
How do I get the raw order XML instead of a PDF?
Use POST /v1/create/cio with the identical request body. It runs the same generation and validation but returns the standalone Cross-Industry Order XML, useful for ERP imports or building the hybrid PDF in your own pipeline.