You connect your accounting system to the Fatoora platform, issue a tax invoice, and wait for the Authority to accept it. Instead of a clean clearance, you get back a response containing error code 1007 and a message stating that the invoice type code is invalid. The invoice stops at the input gate and never even reaches the business-rules check. This page is a dedicated reference for this error alone, within Qoyod’s e-invoicing errors guide.
Error code 1007 concerns a single field in the XML document called InvoiceTypeCode. This field carries two separate values: the document type code (invoice, credit note, debit note), and a seven-digit subcode that describes the nature of the invoice (standard or simplified tax invoice, plus any additional attributes such as self-billing or third-party billing). Any value outside what the Authority accepts in either part produces this error.
The target audience here is the developer or technical integration specialist who builds or maintains the connection between an accounting system and the Fatoora platform. That is why this page contains actual JSON examples of the Authority’s response, along with an explanation of the fields as they appear in the UBL 2.1 document. Technical identifiers such as InvoiceTypeCode and validationResults stay in English because they are actual field names in the standard and must not be translated.
What error code 1007 means exactly
the electronic invoice In Phase Two, the electronic invoice is a structured XML document that follows the UBL 2.1 standard. Every element in it is subject to a validation rule. InvoiceTypeCode is one of the first fields the Authority checks, because it determines the document type and its route. If this field is wrong, there is no point continuing with the rest of the checks.
This error appears in the structure and format layer, that is the first of the four validation layers. The invoice passes through the layers in order and stops at the first layer it fails. This means that when you see code 1007 you do not need to look into the tax calculations or the digital signature, because the invoice has not reached those layers yet.
The error is of the rejection type, not a warning. The errorMessages array in the response contains this code, and whenever it holds any element the invoice is fully rejected. A standard tax invoice is not delivered to the buyer before you correct the value and resend, because the clearance route halts the transaction immediately.
Structure and format ← error 1007 sits here
Business rules BR
Signature and stamp
Clearance or reporting
How the Authority returns this error in the response
When you send the invoice through the clearance or reporting interface, the Authority returns a JSON response containing a validationResults object. This object holds the overall status and the two arrays of errors and warnings. With error 1007 the status is a rejection, and the element appears inside errorMessages as follows.
Read the code field, not the message field. Code 1007 is fixed and identifies the error precisely, whereas the descriptive text in message may be phrased in different ways or translated. Tie your system’s logic to the numeric code to guarantee stable diagnosis across the Authority’s different versions.
Notice that the warningMessages array is empty in this example. The presence of code 1007 inside errorMessages alone is enough to reject the invoice, regardless of any warnings. Fix the error first, then look at the warnings after the invoice is accepted.
Causes of the error: the first part of InvoiceTypeCode
The InvoiceTypeCode field carries the document type code first. This code is a three-digit number taken from an approved list in the UBL standard. The Authority accepts only three values for this part, and any other value produces error 1007.
- 388 for the tax invoice. This code describes the invoice in both its standard tax form (B2B) and its simplified form (B2C). Most issued documents carry this code.
- 383 for the debit note. Used when adding an amount to a previous invoice, such as correcting an undercharge or adding extra fees.
- 381 for the credit note. Used when reducing the value of a previous invoice, such as returns or a partial cancellation.
The common mistake here is that the system places an unapproved code for the document, such as a generic commercial invoice code that the Authority does not accept in the e-invoicing context. Make sure your system’s logic maps the internal document type (invoice, credit note, debit note) to the correct code from the three above, not to any other code from the wide UBL list.
| Code | Type |
|---|---|
| 388 | Tax invoice |
| 383 | Debit note |
| 381 | Credit note |
| Any other code | Produces error 1007 |
Causes of the error: the seven-digit subcode
The second part of the invoice type definition is a seven-digit subcode that appears in an attribute called name inside the InvoiceTypeCode element. These seven digits describe the invoice’s attributes precisely, and each digit has a value of 0 or 1. An error in any digit, or a length other than seven digits, also produces error 1007.
The two most important digits are the first two: they determine whether the invoice is a standard tax invoice or a simplified one.
- The first digit for the standard tax invoice (B2B). It takes the value 1 when the invoice is a standard invoice directed to a business, which is the invoice that goes through clearance.
- The second digit for the simplified invoice (B2C). It takes the value 1 when the invoice is a simplified invoice directed to a consumer, which is the invoice that is reported within 24 hours.
The rule here is strict: only one of the two digits takes the value 1, not both and neither of them zero. An invoice carrying 1 in both digits together, or zero in both together, is an invalid value. This often happens when the system confuses B2B and B2C logic or leaves the field at a wrong default value.
The remaining five digits describe additional attributes: self-billing, where the buyer issues the invoice on behalf of the seller, and third-party billing, where an intermediary issues the invoice, in addition to other attributes such as the export invoice. Each attribute has its own dedicated digit, and activating it in the wrong digit or mixing it with a conflicting attribute rejects the invoice.
An example of the correct structure of the InvoiceTypeCode field as it appears in the XML document of a standard tax invoice:
Here the code 388 means a tax invoice, and the value 0100000 in the name attribute means: the first digit 1 (standard), the second digit 0 (not simplified), and the rest of the digits zeros (no self-billing and no third party). The simplified invoice, on the other hand, carries 0200000, that is zero in the first digit and one in the second. Any mixing between these two patterns is a direct cause of error 1007.
Digits 1–2: the type (01 standard / 02 simplified)
Digit 3: third-party billing
Digit 7: self-billing
0100000 = standard B2B
Self-billing and third-party billing: a hidden source of the error
The five digits that follow the standard and simplified digits describe special cases in the way the invoice is issued. The most confusing of them are the self-billing and third-party billing digits, because many systems activate them by mistake or leave them active from an old configuration.
Self-billing is a case in which the buyer issues the invoice on behalf of the seller, by prior agreement between them. This is a known pattern in some long-term contracts where the buyer has more accurate consumption data than the seller. The digit dedicated to it must take the value 1 only when the invoice is genuinely self-billed, and zero in every ordinary case.
Third-party billing is a case in which an authorized intermediary handles issuing the invoice on the seller’s behalf, such as an accounting firm or a brokerage platform. It has its own independent digit as well. The common mistake is that the system activates one of these two digits with a default value, so the Authority rejects the invoice even though it is an ordinary sale transaction with nothing to do with self-billing or a third party.
The practical rule: start with all five digits as zeros, and do not activate a digit unless its case genuinely applies to the issued invoice. Default activation, or activation copied from an old template, is a recurring cause of error 1007 that is hard to spot because the main code 388 looks correct at first glance.
Credit and debit notes: when the code changes
Many cases of error 1007 arise when issuing notes rather than invoices. When you cancel part of an invoice or receive a return, you are issuing a credit note, not an invoice, and the code must move from 388 to 381. If the system kept the code 388 for a document that is actually a note, the Authority rejected the document.
The same applies to the debit note with code 383, which you issue when you add an amount to a previous invoice, such as correcting an undercharge in the price or later fees that were not accounted for. The code distinguishes the accounting intent of the document, so tying it to the type of internal transaction in your system is a condition for its acceptance.
The note inherits the route of its original invoice. A note on a standard tax invoice goes through clearance, and a note on a simplified invoice is reported within 24 hours. This means the name attribute in the note must also be consistent with the type of the original invoice, so do not make a note on a B2B invoice carry the coding of a B2C invoice.
The most common causes of error 1007
After diagnosing a large number of cases of this error, specific causes recur. The following table summarizes them along with the direct fix for each, to serve as a quick reference when the code appears.
| Cause | Fix |
|---|---|
| An unapproved document type code instead of 388, 383, or 381 | Map the internal document type to one of the three codes only |
| A name attribute with a length other than seven digits | Add a validation that enforces a length of seven digits before sending |
| Activating the standard and simplified digits together or zeroing them together | Activate only one digit according to the customer type |
| Activating the self-billing or third-party digit with a default value | Zero the special digits unless their case genuinely applies |
| Keeping code 388 on a document that is a credit or debit note | Move the code to 381 for a return and 383 for an addition |
How to diagnose the error step by step
When code 1007 comes back, follow a systematic sequence instead of guessing. Correct diagnosis starts from the document you sent, not from the Authority’s response, because the response tells you the error exists but not its exact location.
- Open the sent XML document and search for the InvoiceTypeCode element. This element sits inside the invoice header. To learn its exact position and the rest of the header fields, see the invoice header in XML page. invoice header in XML.
- Check the element’s text value. Is it 388, 383, or 381? Any other value is a direct cause of the error.
- Check the name attribute. Is its length exactly seven digits? Does it carry 1 in only one of the first two digits?
- Match the actual document type with the code. If the invoice is a return, the code must be 381 not 388, and so on.
- Review the additional-attributes logic. If the invoice is not self-billing or third-party, the digits dedicated to them must be zeros.
Remember that the error is in the structure layer, so it is usually a fixed defect in the way the system builds the field, not a transient case. Once you fix the logic once, the problem disappears from all similar invoices at once.
Let your system build the invoice type code for you
Qoyod generates the InvoiceTypeCode field with the correct code and value automatically from your choice of document type and customer, eliminating error 1007 at its root before it reaches the Authority.
How to tell error 1007 apart from neighboring errors
Error 1007 concerns the value of the invoice type field specifically. But integration developers sometimes confuse it with other errors that appear in the same layer or the next layer, so they waste time in the wrong place. Distinguishing them starts from reading the code and the category together.
Errors in the XML_FORMAT category such as 1007 mean a defect in the structure or the value, and are handled in your document before any thought about the calculations. Business-rule category errors, on the other hand, appear after the invoice passes the structure layer, and mean the values are formally sound but not logical, such as the sum of the line items not matching the total.
If you see error 1007 alone, focus on the InvoiceTypeCode field and do not touch the rest of the invoice. And if other errors appear with it, handle 1007 first because it is in an earlier layer, then resend to see whether the other errors are still genuinely present or were dependent on it. This systematic order saves many correction cycles.
How to fix the error and prevent it from recurring
The fix is at the level of the system logic that builds the InvoiceTypeCode field, not at the level of a single invoice. Address the source once and all affected invoices are resolved.
- Map the internal document type to a single explicit code. Make the ordinary invoice produce 388, the return 381, and the extra charges 383, with no ambiguous default values.
- Map the customer type to the correct digit. A business customer activates the first digit (standard), and an individual consumer activates the second digit (simplified), and do not leave the decision to a default value.
- Zero the unused digits. Unless the invoice is explicitly self-billing or third-party, set their digits to zero.
- Check the length before sending. Add a validation that rejects any name value whose length does not equal seven digits.
The most robust prevention is to use a system that handles building this field automatically according to the Phase Two specification, so that you do not write the coding logic manually at all. And to go deeper into the different values and which code suits each case, see the types of electronic invoices in Saudi Arabia.
The error’s impact on the clearance route versus reporting
The outcome of error 1007 differs depending on the invoice type and its route. Understanding this impact precisely determines how urgent the fix is and whether there is an invoice that actually reached the buyer and needs correcting.
In the standard tax invoice (B2B), the route is clearance. The Authority inspects the invoice before delivering it to the buyer, so if error 1007 comes back the transaction stops at this point and the invoice never reaches the buyer at all. The practical impact here is simpler: there is no issued invoice that needs canceling, it is enough to correct the value and resend to obtain the cleared invoice.
In the simplified invoice (B2C), the route is reporting within 24 hours. The invoice may have been delivered to the consumer at the moment of sale before being sent to the Authority. When error 1007 comes back at reporting, you are facing an invoice that exists with the customer but is not correctly reported. Here the fix is more sensitive, because you need to correct the coding and re-report within the deadline, and perhaps issue a note if material data changed.
This difference is another reason to get the invoice type field right at the source. A coding error in a B2B invoice is discovered immediately and corrected before any harm, but a similar error in a high-volume B2C flow may accumulate across hundreds of invoices before anyone notices, turning into a late-reporting burden.
A practical example: from rejection to acceptance
Suppose a store that sells to consumers and issues simplified invoices, but its old system places 0100000 in the name attribute for all invoices. The result is that every simplified invoice is coded as if it were standard, so error 1007 comes back at reporting because the coding does not match the actual nature of the invoice.
The first step is to open the sent XML document and read the InvoiceTypeCode element. The code 388 is correct because it is an invoice, but the name attribute carries 0100000 while the invoice is directed to a consumer. The diagnosis immediately reveals that the first digit is activated by mistake instead of the second.
The second step is to fix the system logic so that it links the customer type to the correct digit: an individual consumer activates the second digit, so the value becomes 0200000. The third step is to resend, so the response comes back with an accepted status and an empty errorMessages array. And since the defect was in the system logic, not in a single invoice, the fix resolves all subsequent simplified invoices in one go.
The lesson is that error 1007 is almost never a single-invoice problem, but a symptom of a flaw in the way the field is built. Fix the logic once, and install a validation that checks the value before sending, and a whole class of rejection disappears.
Test the coding in the sandbox before production
Entering Phase Two passes through a compliance stage in a sandbox environment before production. In this stage your system obtains a compliance identifier (CSID) for testing, and sample invoices are sent to the Authority to confirm that your output complies with the specification. This is the ideal moment to catch coding errors such as 1007 before they touch a real invoice.
Make your test samples cover every case you will actually issue: a standard invoice, a simplified invoice, a credit note, a debit note, and any self-billing or third-party case if it is part of your activity. Each case generates a different InvoiceTypeCode value, and testing it early reveals any flaw in the logic before production.
Once you pass the test samples without error 1007 in any case, move to the production compliance identifier that signs your live invoices. Progressing from the sandbox to production is not a formality but a safety net that prevents a recurring structural error from reaching your actual invoice flow.
Remember that each branch or issuing device needs its own compliance identifier. If you distribute issuing across several points of sale, make sure the logic for building the invoice type field is unified across them all, so that one branch’s coding is not correct while another errs because of an old configuration that was not updated.
How Qoyod helps you avoid error 1007
Qoyod builds the InvoiceTypeCode field automatically according to the UBL 2.1 specification for Phase Two. When you choose the document type inside Qoyod (invoice, credit note, debit note) and the customer type (business or individual), the system translates that choice into the correct code and the correct seven-digit value without any intervention from you. You do not write 388 or 0100000 manually.
Qoyod also handles generating the compliant XML, managing the digital signature, the CSID certificate, and the clearance (B2B) and reporting (B2C) routes automatically. This eliminates a whole class of manual coding errors such as error 1007 at their root. Qoyod also added instant validation of identifier formats on entry, such as the tax number and the commercial registration, catching one of the most common causes of warnings before sending.
It remains for you to register the compliance identifier (CSID) with the Authority once at the start, and Qoyod guides you through this step. After that you issue your Phase Two compliant invoices, reassured that the invoice type field is set correctly in every document.
Frequently asked questions
What does error code 1007 mean exactly?
It means the value of the InvoiceTypeCode field in your invoice is not accepted by the Authority. The cause is either a wrong document type code (not 388, 383, or 381), or a wrong seven-digit subcode in the name attribute. The invoice is rejected until the value is corrected.
What are the correct document type codes?
The Authority accepts only three codes: 388 for the tax invoice in both its standard and simplified forms, 383 for the debit note, and 381 for the credit note. Any other code from the UBL list produces error 1007.
What is the difference between 0100000 and 0200000 in the name attribute?
The value 0100000 means a standard tax invoice directed to a business (B2B) that goes through clearance. The value 0200000 means a simplified invoice directed to a consumer (B2C) that is reported within 24 hours. Mixing the two patterns is a common cause of the error.
Does error 1007 appear in the simplified invoice as it does in the standard one?
Yes. The error concerns the structure of the invoice type field, and it exists in both types. The difference is that the standard invoice stops immediately at clearance, while the simplified one may have been issued to the buyer and the error appears at reporting within 24 hours.
Why should I tie my system’s logic to the code field, not the text?
The code field carries the value 1007, which is fixed and identifies the error precisely. The descriptive text in message may be phrased in different ways or change between the Authority’s versions. Tying to the code guarantees stable diagnosis and accurate tracking of recurrence.
I corrected the document code but error 1007 still appears, why?
The problem is usually in the name attribute, not in the main code. Check that its length is exactly seven digits, that only one of the first two digits carries the value 1, and that the self-billing and third-party digits are zeros unless their case applies. A wrong name value produces the same error even if the code 388 is sound.
Do I need to cancel the invoice rejected with error 1007?
The standard tax invoice was never cleared, so there is no existing invoice that needs canceling; it is enough to correct the value and resend. The simplified invoice, however, may have been delivered to the consumer, so correct the coding and re-report within the 24-hour deadline, and issue a note if material data changed.
Does Qoyod exempt me from setting this field manually?
Yes. Qoyod builds the InvoiceTypeCode field automatically from your choice of document type and customer type, so you do not write the code or the seven-digit value yourself. This eliminates error 1007 at its root. It remains for you to register the compliance identifier with the Authority once at the start.
