Error Code 1013: XML Structure Does Not Match UBL 2.1

You build your integration with the Fatoora platform, send an e-invoice to the test environment, and it comes back rejected with a specific code: 1013. This code tells you that the invoice XML structure does not match the UBL 2.1 standard, so ZATCA rejects it before it even checks the value of any field. The invoice may have every number correct, yet the shape of the document itself does not conform to the template the Fatoora platform expects. This page is a dedicated guide to error code 1013 alone, within the Qoyod e-invoicing.

The difference between this page and the XML errors in e-invoicing general page is one of angle. The general page explains all the patterns of XML errors (malformed syntax, encoding, missing fields, schema violation). Here, though, we focus on code 1013 specifically: when the system issues it, which cases it covers, how to read its message, and how to fix it for good. And to understand the standard itself (what UBL 2.1 is, and how it orders the invoice elements), its reference is the UBL 2.1 standard in e-invoicing. And for an overview of the rest of the platform’s error categories, you will find it in the guide ZATCA e-invoicing errors.

The target audience here is the developer or technical integration lead building the connection of an accounting system to the Fatoora platform. That is why you will find real JSON examples of ZATCA responses, valid and broken XML snippets side by side, and an explanation of each case in a present-the-problem-then-the-solution format. English technical codes such as cbc:ID andcac:InvoiceLine andxmlns stay as they are because they are the actual names of elements in the UBL 2.1 schema.

What error code 1013 means exactly

Code 1013 means the invoice file you sent is not valid XML according to the UBL 2.1 schema that ZATCA has adopted. The Fatoora platform does not check amounts and taxes first; it checks the shape: is the document written in the correct format? Are the elements ordered in the sequence the schema imposes? Are the namespaces declared as they should be? Are the data types valid? If any of these conditions fails, code 1013 is issued and processing stops.

UBL 2.1 is short for Universal Business Language version 2.1. It is an international standard that describes the structure of business documents in XML format. ZATCA adopted this standard as the basis for the e-invoice file in the second phase, and added its own rules through additional business rules. So it is not enough for your file to be syntactically valid XML; it must match this specific template in all its details.

It is important to distinguish between two levels of validation. The first level is XML syntactic validity: are the tags closed? Is the document balanced? Any XML tool covers this. The second level is schema (XSD) conformance: are the elements the same ones UBL 2.1 defines? In the order and types it imposes? Code 1013 concerns this second level specifically. Your document may be perfectly valid syntactically, yet the schema still rejects it because it does not match the template.

This distinction explains why many developers get confused. The developer opens the file in an XML editor and sees it clean and formatted, so they think the problem is somewhere else. But the editor validates the syntax, not the schema. A validation tool against the XSD is the only thing that reveals a UBL 2.1 violation.

A UBL 2.1 violation appears in four main forms: a required element missing, elements in the wrong order, an incorrect namespace, or a data type that does not match what the schema expects. We cover each form on its own, with the broken snippet and its valid counterpart, so you can quickly match it against your rejected document.

ZATCA’s message as it reaches you in the API response

When the invoice is rejected with code 1013, the Fatoora platform returns a JSON response specifying the type of error and its location. This is a real example of the message shape:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1013",
        "category": "XSD_SCHEMA",
        "message": "XML document does not conform to UBL 2.1 schema"
      }
    ],
    "warningMessages": []
  }
}

The field category with the value XSD_SCHEMA is your key. It tells you clearly that the problem is in schema (XSD) conformance, not in the value of a single field. Some validation tools add the location of the violation to the schema message, such as the name of the offending element and the line number. Read those details first, as they shorten your search for where the error is.

Infographic: the four forms of a UBL 2.1 violation

Case one: a required element missing from the document

The most common cause of code 1013 is the absence of an element the UBL 2.1 schema requires. The schema defines mandatory elements the document is not accepted without. Examples are cbc:ProfileID which defines the invoice profile, or cbc:ID which carries the invoice number, or the seller data block. If any mandatory element is dropped, the schema rejects the entire document.

This is a broken snippet missing the node cbc:ProfileID which is supposed to precede the invoice number:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-001</cbc:ID>
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  ...
</Invoice>

and the valid snippet after adding the required element in its correct position before the invoice number:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
  <cbc:ID>INV-001</cbc:ID>
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  ...
</Invoice>

The solution here is direct: review the list of mandatory elements in ZATCA’s invoice specification, and make sure your system’s XML generator writes them all. Do not settle for the elements you think are important, because the schema is not lenient about any element it classifies as mandatory.

Note that some elements are conditionally mandatory. An element may be optional in a simplified B2C invoice and mandatory in a B2B tax invoice, or vice versa. An example is the buyer data that the B2B type imposes and that some B2C cases do not require. So do not build a single list of mandatory elements for all invoices; instead, tie the requirement to the type of invoice you issue. Overlooking this difference is a common cause of code 1013 appearing in one invoice type but not another, even though the generator itself works.

Case two: correct elements but in the wrong order

This case deceives many developers. All the elements are present and their values correct, but they are ordered in a way the schema does not accept. UBL 2.1 imposes a specific sequence for elements within each block. If cbc:IssueDate comes before cbc:ID for example, or an invoice line is placed before the totals data, the schema rejects the document even if every value is valid.

The reason is that XSD uses a xsd:sequence definition that requires the elements to appear in the declared order, not in any order. This differs from other data formats that are lenient about order. A snippet in the wrong order, in which the issue date was placed before the invoice number:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  <cbc:ID>INV-001</cbc:ID>
  ...
</Invoice>

the same snippet in the order the schema imposes: the invoice number first, then the issue date.

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-001</cbc:ID>
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  ...
</Invoice>

The solution is to build the XML generator so that it writes the elements in the sequence declared in the schema, not in the order the data arrives from your database. Do not rely on the order of fields in your system’s objects; instead, tie the writing to the official sequence of the schema.

This case is dangerous because it does not show up in simple manual testing. You write one invoice in the correct order by chance, and it is accepted, so you think the generator is sound. Then the structure of the incoming data changes in another invoice, so the generator writes the elements in a different order, and code 1013 appears suddenly. The cure is for the writing order to be fixed in the template, completely independent of the shape of the incoming data. Adopt a template that defines the sequence once, then only fill in its values.

Case three: an incorrect or missing namespace

UBL 2.1 elements are distributed across XML namespaces. Each prefix such as cbc andcac is tied to a specific namespace that must be declared in the document root. If you omit declaring a namespace, or tie it to a wrong URN, or use a prefix you have not declared, the schema sees the elements as unknown and rejects them with code 1013.

These are the most commonly used namespaces in a UBL 2.1 invoice:

• cbc is tied to urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2 and covers the basic fields such as the invoice number and its date.
• cac is tied to urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2 and covers the composite blocks such as the seller data and the invoice lines.
• the default namespace of the root Invoice is tied to urn:oasis:names:specification:ubl:schema:xsd:Invoice-2.

The common error is forgetting to declare cac or writing the URN with a typo. A broken snippet that uses the prefix cbc without declaring it in the root:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-001</cbc:ID>
</Invoice>

the valid snippet after declaring the namespaces in full in the root element:

<Invoice
  xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
  xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
  xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
  <cbc:ID>INV-001</cbc:ID>
</Invoice>

The solution is to declare all the namespaces you use in the root element once, with the literal URNs exactly as they appear in the specification. Copy the URNs verbatim, because a single missing character is enough to issue code 1013.

Case four: a data type that does not match what the schema expects

The schema does not only define the elements and their order; it also defines the data type of each value. A date field must be in a date format, an amount field must be a decimal number, and some fields require a mandatory attribute such as the currency unit. If you put text in a numeric field, or a date in a non-standard format, or omit a mandatory attribute, code 1013 is issued for a data type violation.

A common example is the amount field cbc:PayableAmount which requires a mandatory currencyID attribute. A broken snippet that writes the amount without the currency attribute:

<cac:LegalMonetaryTotal>
  <cbc:PayableAmount>115.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>

the valid snippet after adding the currency attribute with the value of the Saudi riyal:

<cac:LegalMonetaryTotal>
  <cbc:PayableAmount currencyID="SAR">115.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>

The solution is to match the type of each value with what the schema requires: dates in YYYY-MM-DDformat, amounts as decimal numbers with the currency attribute, and quantities as numbers with the unit of measure when required. Validate the values before building the document, not after sending it.

Currency attributes are a recurring source of this case. The UBL 2.1 schema requires a currencyID attribute on amount fields, and may require the currency to match across all invoice fields. If you write a currency in one field and omit it in another, or mix different currency codes, code 1013 is issued. Make the currency a unified value at the document level, and apply it to every amount field automatically instead of writing it by hand in each place.

Decimal numbers are another source. Some programming languages write numbers with a local decimal comma or with thousands separators, and this violates what the schema expects. Write amounts with an English decimal point and without thousands separators, and set the number of decimal places as the specification requires. Formatting numbers according to the server’s locale is a common error that generates code 1013 in production when the server settings change.

How to read the code 1013 message and diagnose it step by step

When code 1013 arrives, follow a fixed sequence that leads you to the location of the violation quickly instead of guessing:

1. Read the message field in the API response. Many validation tools mention the name of the offending element and its line number.
2. Save the rejected XML file as is, then validate it locally against ZATCA’s official XSD files before resending.
3. Start from the four forms in order: missing element, then wrong order, then namespace, then data type. Most cases fall in the first two forms.
4. Compare your document with a valid invoice sample approved by ZATCA. Structural differences show up quickly in a direct comparison.
5. After the fix, revalidate locally first, then send to the test environment before production.

A local validation tool against the XSD is the fastest route. It reveals the violation on your machine in seconds, so it does not consume your submission attempts to ZATCA in trial and error.

When reading the error message from an XSD tool, pay attention to the path of the offending element that the tool usually mentions. The path tells you which block the error is in, such as a specific invoice line or the totals block or the seller data. This narrows your search to one place instead of reviewing the whole document. Start from the element the tool mentioned, and examine what comes before and after it, because the violation is usually in the order of its neighbor or in a mandatory element dropped from it.

If the tool does not mention a clear location, split the document. Build a minimal copy containing only the mandatory elements and validate it; if it is accepted, add the blocks gradually until the violation appears. This split isolates the block responsible for code 1013 quickly, even in large documents.

Infographic: the code 1013 diagnosis path

Let Qoyod build the XML for you

The four forms of code 1013 share one root: manual or incomplete XML building that does not precisely match the schema. When an integrated accounting system takes over generating the document, these forms disappear because the generator writes all the mandatory elements, in the correct order, with the declared namespaces, and with matching data types.

How Qoyod helps you avoid code 1013

Qoyod is compliant with the second phase of e-invoicing, and it generates the invoice XML file according to the UBL 2.1 schema that ZATCA adopted automatically. This means you do not write the document by hand, and you do not track the mandatory elements or their order or their namespaces. Qoyod puts these rules in place by default with every invoice you issue.

In practice, Qoyod builds the document with the full mandatory elements, in the sequence the schema imposes, with the namespaces declared in the root, and with the data types matching each field, including currency and unit attributes. Qoyod also manages the digital signature, the CSID certificate, the unique identifier, and the QR code, so the invoice comes out ready for clearance or reporting without manual intervention in the XML structure.

The establishment’s role remains in registering with ZATCA and linking its own CSID certificate, and Qoyod guides you through this step. After that, the system takes over building the compliant document, so you do not face code 1013 because the shape is correct from the start.

The structural difference between a B2B invoice and a B2C invoice

Before you look for the cause of code 1013, make sure you are building the correct structure for the invoice type. The UBL 2.1 schema is one, but ZATCA’s rules impose different fields depending on the document type. The B2B tax invoice directed at a registered establishment, and the simplified B2C invoice directed at a final consumer, differ in some mandatory elements.

The B2B tax invoice requires the buyer’s full data, including their tax number, because it passes through the clearance path before reaching the buyer. The absence of the buyer data block in a B2B invoice is a structural violation that issues code 1013. The simplified B2C invoice, on the other hand, does not require the buyer’s tax number, and passes through the reporting path within twenty-four hours of its issuance.

The common error is for the developer to build a single template for all invoices, so they put B2B-specific fields in a B2C invoice or vice versa. The result is a schema violation because the element is mandatory in one type and optional or forbidden in the other. Determine the invoice type at the start of the build, choose the matching template, then fill in its values. This prevents a whole class of code 1013 cases that appear in one invoice type but not another.

When code 1013 appears in testing and when in production

Code 1013 is issued most during the integration and testing phase, when the development team builds the XML generator for the first time. This is the natural phase for discovering structural violations and fixing them before moving to production. Once the generator settles on a matching structure, the code practically disappears.

If code 1013 appears in production after a period of stability, the likeliest cause is that a change was made to the XML generator: a code edit that added an element in the wrong place, or removed a namespace, or changed a field’s data type. In that case, review the last change that touched the document build, and compare its output with a sample that was previously accepted.

This difference matters in diagnosis. An error in testing is usually an initial build problem that was not completed. And an error in production is usually a regression after an edit. Determine which environment issued the code before you look for the cause.

A practical checklist to prevent code 1013

This checklist turns code 1013 from a recurring error into a rare case that you catch before it reaches ZATCA:

• Validate every document locally against the official XSD files before any submission to ZATCA.
• Write the elements in the sequence the schema declares, not in the order the data arrives from your database.
• Declare the namespaces in full in the root element, and copy their URNs verbatim from the specification.
• Match the type of each value with the schema: standard dates, decimal amounts with the currency attribute, quantities with the unit of measure.
• Keep a reference invoice sample accepted by ZATCA to compare any rejected document against.
• Add an automated validation test within the deployment pipeline (CI) that blocks the release of any edit that breaks schema conformance.

Infographic: a checklist to prevent code 1013

From fixing the invoice to fixing the build logic

Fixing a single invoice rejected by code 1013 is easy: add the missing element, or reorder the elements, or declare the namespace, then resend. But this treats the symptom, not the root. If the XML generator keeps writing documents in the same wrong pattern, the code will return with every new invoice.

The root cure is to fix the build logic: tie the writing of elements to the schema sequence, make declaring the namespaces a fixed part of the template, and add a local validation layer before sending. Once you stabilize these layers and test them, your fix holds as the volume of invoices grows because it treats the logic, not the symptoms. And if you want to avoid writing this logic from scratch, adopting an accounting system that takes over building compliant XML puts these layers in place by default, so you start from a point free of code 1013.

Frequently asked questions

What is the difference between code 1013 and other XML errors?

Code 1013 concerns specifically the document structure not matching the UBL 2.1 schema, that is, a violation of the shape (XSD). Other XML errors may concern malformed syntax, encoding, or field content. For a full picture of XML error patterns, see the page XML errors in e-invoicing.

How do I validate an XML file against UBL 2.1 before sending?

Download ZATCA’s official invoice XSD files, then use a local XML validation tool to match your document against them. The tool reveals the violation on your machine in seconds, so it does not consume your submission attempts to ZATCA. To understand the standard itself, see the page UBL 2.1 standard.

Does the order of elements in XML really matter?

Yes. The UBL 2.1 schema uses a specific sequence that requires elements to appear in their declared order. A correct-value element in the wrong place is enough to issue code 1013, so write the elements in the schema’s order, not in the order the data arrives.

Why is my invoice rejected with code 1013 even though all its numbers are correct?

Because the Fatoora platform checks the shape before the values. If the structure violates the schema, code 1013 is issued even if all the amounts and taxes are valid. Fix the structure first, because processing will not reach the value check before that.

Is fixing a single invoice enough to solve code 1013 for good?

No. Fixing a single invoice treats the symptom. If the XML generator keeps writing in the wrong pattern, the code will return with every invoice. Fix the build logic itself and add local validation within the deployment pipeline so the error does not recur.

How do I avoid code 1013 without building an XML generator myself?

Use an integrated accounting system that builds UBL 2.1-compliant XML for you. Qoyod generates the mandatory elements with their order, namespaces, and data types automatically, so code 1013 never reaches you in the first place.