CIO Creation API Reference

Technical reference for generating standalone UN/CEFACT Cross-Industry Order (CIO D20B) XML documents from a structured JSON request. CIO is the payload inside every Order-X hybrid PDF, the ordering counterpart of the Cross-Industry Invoice. The endpoint accepts the same request body as POST /v1/create/order-x and returns the validated XML on its own, ready for ERP import, direct transmission, or embedding in your own pipeline.

POST https://api.invoicexml.com/v1/create/cio

Example request

curl -X POST https://api.invoicexml.com/v1/create/cio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o order-cio.xml \
  -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" }
  }'

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.

Headers

Header	Value
Authorization *	Bearer YOUR_API_KEY
Content-Type	application/json

Response

200 Generated CIO XML

The purchase order was generated and validated. The response body is the standalone Cross-Industry Order XML, returned as a file download.

Content-Type: application/xml

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 finished hybrid PDF instead?

POST /v1/create/order-x accepts the identical request body and returns a complete Order-X hybrid PDF/A-3 with the XML already embedded as order-x.xml.

Order-X PDF API

Frequently Asked Questions

What is a Cross-Industry Order (CIO)?

CIO is the UN/CEFACT XML message for purchase orders, the ordering sibling of the Cross-Industry Invoice (CII) that powers Factur-X and ZUGFeRD. Order-X 1.0 is built on the CIO D20B release; the root element is SCRDMCCBDACIOMessageStructure and the reusable vocabularies are the :128 releases rather than the :100 ones the invoice uses.

How does this differ from /create/order-x?

Same request, same generation, same Order-X 1.0 validation; only the packaging differs. This endpoint returns the raw CIO XML (Content-Type application/xml), while /v1/create/order-x wraps that XML into a hybrid PDF/A-3 with Order-X XMP metadata. Choose CIO when a system wants the XML alone.

Which guideline identifier does the output declare?

The Order-X profile identifier matching options.profile: urn:order-x.eu:1p0:basic, urn:order-x.eu:1p0:comfort (the default), or urn:order-x.eu:1p0:extended. The document is validated against exactly that profile's schema and rules before delivery, so the declaration always matches what was checked.

Can I turn the CIO into an Order-X PDF later?

The cleanest way is to call /v1/create/order-x with the same request body and receive the finished hybrid in one step. If you embed in your own pipeline instead, attach the XML to a PDF/A-3 as order-x.xml with an AFRelationship and Order-X XMP metadata (fx:DocumentType ORDER), per the Order-X specification.

Is the output validated automatically?

Yes. Every generated order is validated against the official Order-X 1.0 XSD and business rules for its profile before delivery. Orders are not EN 16931 documents, so no invoice rule set runs; a failed validation returns a 400 response with errorCode 4001 and structured findings.

What does options.typeCode control?

The UNTDID 1001 document type: 220 order (the default), 230 order change, or 231 order response, written into the CIO's ExchangedDocument type code.