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 schema and business rules before the PDF is assembled.

New to the format? The Order-X API overview covers profiles, type codes, and validation in one page.

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, options.logoUrl 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.

POST 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", "logoUrl": "https://example.com/logo.png" }
  }'

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 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.logoUrl	string	Public URL of your logo, printed top-left on the rendered template (PNG or JPEG, up to 2 MB, scaled to fit with its aspect ratio preserved). Fetched with the same protections as `pdfUrl` and re-encoded before embedding. 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.
options.validationLanguage	string	Language of the finding messages when the request is rejected: `en` (default), `de`, or `fr`. Only each finding's `message` changes; `rule`, `fields` and `raw` stay the same. Order-X rule findings keep the rule set's own English wording in every language. Independent of `options.language`; any other value is rejected with a 400 (`errorCode` 4002). See localized error messages.

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.

Content-Type: application/pdf

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.

CIO XML API

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 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) and options.logoUrl (a public PNG or JPEG, up to 2 MB, printed top-left).

Is the output validated automatically?

Yes. The generated Cross-Industry Order is validated against the official Order-X 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.