What Order-X is
An Order-X file is a PDF/A-3 with three defining properties:
A visual layer for people. The PDF pages show the order the way a buyer or supplier expects to read it. For approval flows, archives, and every process that still runs on "attach it to the email", the file behaves like the purchase orders everyone already handles.
A data layer for machines. Embedded in the container is order-x.xml, a UN/CEFACT Cross-Industry Order document carrying the structured order data: parties, line items, quantities, prices, references, delivery details. A receiving system extracts the XML and books the order without OCR or retyping.
Metadata that declares what the file is. The PDF's XMP metadata declares the Order-X document type and the conformance profile, so software can recognize the file for what it is before touching the XML.
If that description sounds like Factur-X, that is the point: Order-X is the same architecture with an order payload instead of an invoice payload. The standard exists because procurement deserves the same automation invoicing got, and because a supply chain that exchanges structured orders can match invoices against them automatically later (the purchase order reference on an EN 16931 invoice, BT-13, suddenly has a structured document behind it).
Profiles and type codes
Two small decisions shape every Order-X integration, and both are single request fields in the API.
The profile is the conformance level of the XML, mirroring the Factur-X ladder:
| Profile | options.profile | When to use it |
|---|
| BASIC | basic | Core order data for straightforward transactions. |
| COMFORT | comfort (default) | The full commercial detail a typical order dialogue needs. The right choice unless you know otherwise. |
| EXTENDED | extended | The complete UN/CEFACT breadth for complex procurement scenarios. |
The type code (UNTDID 1001) says which stage of the order dialogue the document carries:
| Code | options.typeCode | Document |
|---|
| 220 | "220" (default) | Order: the buyer's purchase order. |
| 230 | "230" | Order change: the buyer amends a previously sent order. |
| 231 | "231" | Order response: the supplier accepts, amends, or declines. |
Together they make the full dialogue expressible in one endpoint: the buyer issues a 220, follows up with a 230 when quantities move, and the supplier answers with a 231, all as hybrid documents both sides can read and process.
Create an Order-X hybrid
POST /v1/create/order-x takes the order as structured JSON, in the same BT-style document model the invoice endpoints use, where the document number field carries the order number. The API builds the CIO XML, validates it against the declared profile, renders the visual layer titled as a purchase order, embeds the XML, and returns the finished PDF/A-3:
curl -X POST https://api.invoicexml.com/v1/create/order-x \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order": {
"invoiceNumber": "PO-2026-0142",
"issueDate": "2026-09-29",
"currency": "EUR",
"buyerReference": "PROJ-88",
"seller": {
"name": "Bauteile Nord GmbH",
"vatIdentifier": "DE123456789",
"postalAddress": { "line1": "Industrieweg 4", "postCode": "28195", "city": "Bremen", "country": "DE" }
},
"buyer": {
"name": "Maschinenbau Sued AG",
"postalAddress": { "line1": "Werkstrasse 20", "postCode": "70173", "city": "Stuttgart", "country": "DE" }
},
"lines": [
{
"quantity": 500,
"unitCode": "H87",
"item": { "name": "Linearlager LM12UU" },
"priceDetails": { "netPrice": 3.40 },
"vatInformation": { "rate": 19 }
}
]
},
"options": { "profile": "comfort", "typeCode": "220" }
}' \
--output order-x.pdf
An order change reuses the same request with "typeCode": "230"; the supplier's response is "231". The response file's XMP declares the Order-X document type, and the embedded order-x.xml carries the profile in its guideline identifier, which is what validators key on later.
Your own PDF, or XML only
Two variations cover the remaining integration shapes:
Your own visual layer. If your ERP already renders purchase orders in your house layout, set options.pdfUrl to the PDF's location and the API embeds the validated CIO XML into your design instead of generating one, returning the hybrid with your pages and the standard's data layer.
XML without the container. POST /v1/create/cio is the same document model with a plain Cross-Industry Order XML response, no PDF involved. It mirrors the relationship /v1/create/cii has to the invoice hybrids: the payload alone, for channels that exchange raw XML or systems that do their own packaging.
Validate Order-X and CIO files
POST /v1/validate/order-x takes either container shape: a hybrid Order-X PDF, from which the embedded order-x.xml is extracted automatically, or a raw CIO XML file directly. The endpoint reads the guideline identifier, validates against the declared profile's schema, and returns the verdict as structured JSON; unknown guideline identifiers fall back to COMFORT validation with an advisory saying so:
curl -X POST https://api.invoicexml.com/v1/validate/order-x \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]"
Files from any producer are accepted, which gives the endpoint the same two roles its invoice siblings have: an intake check on orders your suppliers or customers send, and an independent verdict on your own output while you build. For the human side of that loop, POST /v1/validate/order-x/report runs the same validation and returns a shareable PDF report instead of JSON, which is the artifact you attach when telling a trading partner what is wrong with their file.
A document that is not a Cross-Industry Order at all (an invoice uploaded by mistake, say) is identified as such rather than drowned in schema errors, and a PDF with no embedded XML gets a clear verdict naming that as the problem.
Order-X next to Factur-X in one integration
The practical payoff of the family resemblance is that order and invoice flows share one integration pattern. The same JSON document model describes both; what changes is the endpoint and, later, the direction:
| Flow | Document | Endpoint |
|---|
| Buyer orders | Order-X (220) | POST /v1/create/order-x |
| Buyer amends | Order-X (230) | POST /v1/create/order-x |
| Supplier responds | Order-X (231) | POST /v1/create/order-x |
| Supplier invoices | Factur-X or ZUGFeRD, carrying the PO number in BT-13 | POST /v1/create/facturx |
| Either side checks a received file | Any of the above | POST /v1/validate/order-x, /v1/validate/facturx |
Teams that adopted the hybrid model for invoices under the French and German mandates get the order side almost for free: the request model is already mapped from their ERP, and the purchase order reference that three-way matching depends on now points at a structured document. The Factur-X technical overview covers the invoice half of that pairing in depth.
Where Order-X support lives
One honest scope note so nobody designs against the wrong surface: Order-X is available through the REST API only. The InvoiceXML MCP server and the Zapier apps cover the invoice formats and do not expose the Order-X endpoints. If your integration runs through either of those, the order flow is a direct HTTP call alongside them, using the same API key.
Get started
The fastest way in is one request: take the curl example above, swap in your own order data, and open the PDF that comes back, then upload it to the validator and read a clean verdict. Create a free InvoiceXML account → and get 100 credits for free, no credit card required.
Related resources:
InvoiceXML is a REST API for European e-invoice compliance covering Factur-X, ZUGFeRD, XRechnung, Peppol UBL, CII, and Order-X purchase orders. Stateless processing, GDPR compliant by architecture, and callable from any stack with an HTTP client.