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 schema and business rules; findings are returned as structured JSON.
New to the format? The Order-X API overview covers profiles, type codes, and validation in one page.
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. |
| validationLanguage | string | Optional. Language of the finding messages: en (default), de or fr, in any letter case. The message of each entry in errors and warnings and the name of each report row change; rule, btCodes, fields, code and raw stay the same. Order-X rule findings keep the rule set's own English wording in every language. Any other value, regional tags such as de-DE included, is rejected with a 400 (errorCode 4002). See localized error messages. |
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 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.
{
"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; raw adds 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 needs a Cross-Industry Order, but this document is a CII invoice. Validate it as a CII, Factur-X or ZUGFeRD invoice instead.",
"btCodes": [],
"fields": [],
"raw": "Root element is 'CrossIndustryInvoice'; expected rsm:SCRDMCCBDACIOMessageStructure. Validate it via /v1/validate/cii, /v1/validate/facturx, or /v1/validate/zugferd instead."
}
],
"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.