Order-X Validation API Reference

Technical reference for validating Order-X purchase orders. Unlike the invoice validators, one endpoint accepts both containers: upload the hybrid Order-X PDF and the embedded order-x.xml attachment is extracted, or upload the raw Cross-Industry Order XML directly. The profile declared in the order's guideline identifier (BASIC, COMFORT, or EXTENDED) selects the official Order-X 1.0 schema and business rules; findings are returned as structured JSON.

POST https://api.invoicexml.com/v1/validate/order-x

Code Example

curl -X POST https://api.invoicexml.com/v1/validate/order-x \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

The Order-X profile is detected automatically from the uploaded file, so you never need to pass it. The detected profile is returned in the response.

Request

Parameter	Type	Description
file *	binary	The order file to validate. Accepted formats: an Order-X hybrid PDF (the embedded order-x.xml attachment is extracted automatically) or a standalone Cross-Industry Order XML file. Invoices are rejected with an ORDER-SYNTAX finding pointing at the right endpoint.

Content-Type: multipart/form-data

That is the whole request. The Order-X profile (BASIC, COMFORT, or EXTENDED) is detected automatically from the order's guideline identifier, the matching Order-X 1.0 rule set is applied, and the response reports what was validated against in data.profile and data.customizationId.

Headers

Header	Value
Authorization *	Bearer YOUR_API_KEY
Content-Type	multipart/form-data

Response

200 Valid order

The order passed every check. valid is true and errors is empty. Note that unlike the invoice validators, Order-X responses carry no EN 16931 field-by-field report array.

Content-Type: application/json

{
  "valid": true,
  "detail": "Your order is Order-X COMFORT compliant.",
  "data": {
    "schemaValid": true,
    "schematronValid": true,
    "conformanceLevel": "Order-X",
    "profile": "comfort",
    "customizationId": "urn:order-x.eu:1p0:comfort"
  },
  "errors": [],
  "warnings": []
}

200 Invalid order

Validation still returns HTTP 200. valid is false and the findings are in the errors array, each tagged with the layer (xsd or cius) that produced it.

{
  "valid": false,
  "detail": "Validation failed with 2 error(s)",
  "data": {
    "schemaValid": false,
    "schematronValid": false,
    "conformanceLevel": "Order-X",
    "profile": "comfort",
    "customizationId": "urn:order-x.eu:1p0:comfort"
  },
  "errors": [
    {
      "rule": "XSD",
      "layer": "xsd",
      "line": null,
      "message": "The required attribute 'mimeCode' is missing.",
      "btCodes": [],
      "fields": [],
      "raw": "[XSD] XSD: The required attribute 'mimeCode' is missing. (Line 116, Col 10)"
    },
    {
      "rule": "UNKNOWN",
      "layer": "cius",
      "line": null,
      "message": "Attribute '@mimeCode' is required in this context.",
      "btCodes": [],
      "fields": [],
      "raw": "Attribute '@mimeCode' is required in this context. (at /SCRDMCCBDACIOMessageStructure/SupplyChainTradeTransaction/ApplicableHeaderTradeAgreement/AdditionalReferencedDocument/AttachmentBinaryObject)"
    }
  ],
  "warnings": []
}

200 Container problems

Two upload situations return a verdict rather than a transport error, each as a single self-contained finding: a PDF without the order-x.xml attachment (rule PDF-EMBED, with data.hasEmbeddedXml false), and a document that is not a Cross-Industry Order at all (rule ORDER-SYNTAX, naming what it is and which invoice endpoint to use instead).

{
  "valid": false,
  "detail": "The uploaded document is not a Cross-Industry Order.",
  "data": { "schemaValid": false, "schematronValid": false },
  "errors": [
    {
      "rule": "ORDER-SYNTAX",
      "line": null,
      "message": "Order-X validation expects a UN/CEFACT Cross-Industry Order (rsm:SCRDMCCBDACIOMessageStructure), but the document is a CII invoice. Validate it via /v1/validate/cii, /v1/validate/facturx, or /v1/validate/zugferd instead.",
      "btCodes": [],
      "fields": [],
      "raw": "Root element is 'CrossIndustryInvoice'; expected rsm:SCRDMCCBDACIOMessageStructure."
    }
  ],
  "warnings": []
}

Status codes

Status	Meaning	Action
200	Validation completed. Check `valid` to determine compliance.	If `valid` is `false`, inspect the `errors` array.
401	Missing or invalid API key.	Check the `Authorization` header.
422	File is not a valid PDF or XML document.	Ensure you are uploading a supported file format.

Findings use the same structured shape as the invoice validators (rule, layer, message, raw), documented in full on the CII validation reference. Order findings reference the CIO structure in raw rather than EN 16931 Business Terms, so btCodes and fields are empty, and the report array is null.

Prefer a printable PDF report?

The PDF report variant of this endpoint (/v1/validate/order-x/report) runs the identical validation and returns a downloadable PDF compliance report, with the verdict in the X-Invoice-Valid response header.

PDF report API

Frequently Asked Questions

Which rule sets does POST /v1/validate/order-x run?

The official Order-X 1.0 validation artifacts: the profile-restricted Cross-Industry Order (CIO D20B) XSD first, then the profile's business rules, which enforce the specification's occurrence tables, required attributes, and code lists. Orders are not EN 16931 documents, so no invoice rule set runs; each finding's layer field reports xsd or cius.

Can I upload both PDFs and XML files?

Yes, and that is a deliberate difference from the invoice validators. A PDF upload has its order-x.xml attachment extracted and validated; an XML upload is validated directly. A PDF without the attachment returns valid false with a PDF-EMBED finding and data.hasEmbeddedXml false.

How is the Order-X profile determined?

From the guideline identifier the order declares (urn:order-x.eu:1p0:basic, comfort, or extended), reported back in data.profile with data.customizationId echoing the raw identifier. An unknown identifier is validated against the COMFORT rules and a PROFILE-DETECTION warning explains the fallback; the document is never auto-failed just for declaring an exotic identifier.

What happens if I upload an invoice by mistake?

The endpoint answers with valid false and a single ORDER-SYNTAX finding naming what the document actually is: a CII invoice is pointed at POST /v1/validate/cii, /facturx, or /zugferd, and a UBL invoice at POST /v1/validate/ubl. You get a precise redirect instead of a cryptic root-element schema error.

Why does the response carry no report array?

The field-by-field report on the invoice validators is built from the EN 16931 Business Term registry, which does not apply to orders. Order-X responses return report as null; the errors and warnings arrays carry the same structured finding shape as every other validator, including rule ids and XML locations.

Is there a printable PDF report variant?

Yes: POST /v1/validate/order-x/report runs the identical validation and returns a printable PDF compliance report instead of JSON, with the pass/fail verdict in the X-Invoice-Valid response header. One credit per call, the same as this endpoint.