You sent an invoice to the National Invoicing System, then found a mistake in it. The buyer’s name is wrong, the quantity is higher than it should be, or the tax rate was entered incorrectly. Every taxpayer asks the same question at this moment: how do I edit the invoice?
The direct answer: the National Invoicing System has no procedure for editing an issued invoice. The technical integration guide published by the Income and Sales Tax Department (ISTD) does not define an edit operation at all. Once an invoice reaches the system and receives a QR code, it is a final document. Correction happens through a second document, never by changing the first one.
This guide explains one thing precisely: why no edit exists, what the official alternative path is, and where its limits are. It does not cover how to register with the system, the mandatory invoice fields, or the technical integration mechanics. Each of those has its own article in this track.
Why an issued invoice cannot be edited
The technical guide defines only two document types, and the type is set in the cbc:InvoiceTypeCode element:
- Value
388: a new invoice. - Value
381: a return invoice, which is legally a credit note.
There is no third type. There is no edit type, and there is no debit note. Any claim about “editing the invoice on the system” or about debit notes in the National Invoicing System has no basis in the official guide.
The reasoning is sound. Once approved, the invoice carries a QR code issued by the system itself, and that code holds the invoice’s core data inside it. Any later change to amounts or names would make the printed code stop matching the data, and the document would lose its evidentiary value. Correction is therefore built on the principle of a continuous record: the original document stays, and a document that reverses it wholly or partly is added alongside it.
A common source of confusion: the ALREADY_SUBMITTED status
If you resend the invoice with the same number and the same unique identifier, the system responds with ALREADY_SUBMITTED and returns the original QR code. This is not an edit, and it does not create a second invoice. It is the documented way to recover a code you lost earlier, for example when the connection dropped before you stored the response.
This is also why the guide states an explicit rule: when a send fails, retry with the same invoice number and the same unique identifier. Generating a new identifier on each attempt produces duplicate invoices in the system, and that is harder to resolve than the original error.
The official alternative: the return invoice
The only approved correction is to issue a return invoice that references the original. It is an independent document, sent to the system like any invoice, but with type 381 and a reference that links it to the original.
What a return invoice must carry
The guide requires three elements that cannot be omitted:
- A reference to the original invoice in the
cac:BillingReferencenode, covering the original invoice number, its unique identifier, and its total value. - A reason for the return, which is mandatory. It is entered as free text in the
cbc:InstructionNoteelement inside thecac:PaymentMeansnode, with payment means code10. - The same invoice type code and currency. The return invoice inherits the name attribute and the currency from the original, and only the document type changes to
381.
An example of how to read the code: name="011">381 means a return against a local cash income invoice.
The limits you need to know before you design around it
These limits separate a correct understanding of the system from an attempt to use it for something it was not built for:
- Returns are on quantities only. The system does not accept a return based on a bare value, only on a returned quantity of a specific line.
- You cannot exceed the quantity sold on the original invoice.
- Multiple partial returns are allowed against the same invoice until the quantities are exhausted.
- Buyer data on a return invoice is a fixed description, neither changed nor added to.
- The line number on the original invoice is the key. It must be stored, because returns are matched on it.
The practical consequence: the system corrects errors that translate into quantities, and does not correct every error you can imagine. That leads to the most important distinction in this guide.
Not every error is fixed with a return invoice
Invoice errors come in two kinds, and the path for each is completely different.
Kind one: an error in the transaction itself
The quantity is higher than ordered, the goods came back, the sale was cancelled, or the price is above what was agreed. These errors map onto quantities and values, and they have a clear path: a full or partial return invoice, then a new invoice with the correct data if the sale still stands.
Kind two: an error in data that cannot be returned
A misspelled buyer name, an incorrect tax number, an unsuitable invoice type code, or a tax rate outside the accepted list. There is no edit for these, and a partial return does not address them, because returns are quantity-based. The practical path is to return the invoice in full and then issue a correct new one.
This is where validating before sending earns its value. Every error you prevent before sending saves two documents: a return invoice and a new invoice. See e-invoicing requirements in Jordan for the mandatory fields to validate before the invoice reaches the system, and general sales tax in Jordan for the accepted rates and how they are calculated.
The invoice type code: why it matters when you return
We said the return invoice inherits the invoice type code from the original. To understand what that means in practice, you need to know how the code is built. The name attribute on the invoice type element is a three-digit number, and each digit carries an independent meaning:
- First digit: trade type. Local, export, development areas, transit, foreign trade, or transfer inside the free zones.
- Second digit: payment method.
1for cash,2for credit. - Third digit: tax family.
1for an income invoice,2for general sales tax,3for special sales tax.
So 011 means a local cash invoice on income tax, and 022 means a local credit invoice on general sales tax. This explains a common error: simplifying the code to “012 is cash and 022 is credit” is wrong outside the scope of the local general-sales-tax invoice, because the third digit changes with the tax family.
This matters twice over when correcting. First, if you get this code wrong at issuance, the error is of the second kind, which a partial return does not fix; it requires a full return and reissue. Second, the return invoice itself must carry the same code, so changing it turns the return into a document that does not match its original.
An important note for specific types: on export, development-area, transit, foreign-trade, and free-zone-transfer invoices, the tax rate must be zero on every line. And on development-area invoices in particular, the buyer’s tax number is mandatory, the buyer must be registered in the development areas, and a valid exemption letter must be recorded on the system.
Rates and tax categories: a common source of second-kind errors
An unaccepted tax rate is one of the most frequent reasons an invoice is rejected, and it is an error a partial return does not address. The accepted general sales tax rates are a closed list: zero, 1%, 2%, 3%, 4%, 5%, 7%, 8%, 10%, and 16%. Any rate outside this list is a known cause of a failed send.
Alongside the rate, there is a tax category that must agree with it:
- Category
S: taxable at a rate other than zero. - Category
Z: exempt, with a zero rate. - Category
O: zero-rated, with a zero rate.
The rule many systems get wrong: if the rate is zero, the category must be O, not S. Confusing the two produces an explicit error message stating that the general tax percentage must be zero.
The income invoice is a different case entirely: it carries no tax node at all. Its lines are quantity, price, discount, and name only. So sending an income invoice from a taxpayer registered for general sales tax, or the reverse, produces a message stating that this user is not authorized to submit this type of invoice.
Discounts and totals: the rule that forces a specific design
This is a technical point with a direct accounting consequence: the system does not accept a discount at invoice level. A discount is entered at line level only, and as a positive value. So if your system grants a trade discount on the invoice total, it must distribute that discount across the lines before sending.
Invoice totals are therefore computed from the lines:
- The line amount equals quantity multiplied by the pre-tax unit price, minus the discount.
- The line tax amount equals the line amount multiplied by the tax rate.
- The line rounded amount equals the line amount plus the tax amount.
- At invoice level, the tax-exclusive amount is the sum of quantity times price, and the payable amount is the sum of the rounded amounts.
Rounding is allowed to three decimal places, with a maximum of nine, within a tolerance of no more than one thousandth. Any arithmetic deviation produces a message stating that the total general amount is not correct, one of the most common error messages. This is a further reason to get the arithmetic right before sending: a rounding error means a full return and a reissue, not an edit.
How to read the system response and know you do not need a return at all
Many “there is an error in the invoice” cases are not invoice errors at all, but a misreading of the system response. The response carries several elements, and the most important is not the technical status code:
- The invoice status is the real reference for whether the invoice was accepted or rejected.
- The QR code is returned on acceptance, and must be printed on the seller’s invoice.
- The invoice number and its unique identifier come back in the response for matching.
- The signed invoice is produced by the system itself, not by the taxpayer.
- The error message carries the rejection detail when there is one.
There are three invoice statuses: accepted with a QR code, already submitted with the original code returned, or not accepted with no code and no identifier returned.
The decisive rule: never judge the invoice from the technical status code alone. Read the invoice status. An invoice can return a technical status code that looks successful and still not be accepted, and the reverse holds in the resend case.
The error messages that mean “reissue”, not “edit”
The following are all second-kind errors, meaning a partial return cannot address them: an incorrect general total, a user not authorized to submit this invoice type, a missing buyer name, a line number that is not unique within the invoice, a general tax percentage that must be zero, a buyer tax number not associated with the development areas, an incorrect postal-code length, and an invalid document structure.
The technical status codes carry different meanings: an internal server error usually means a wrong tax number, a wrong income-source sequence, or a tax rate outside the list; a forbidden response means wrong linking credentials; and a gateway timeout means the system could not be reached because of a firewall or an issue on the other side. None of these calls for a return invoice, because the invoice was never accepted. A return only ever applies to an accepted invoice.
This distinction is the core of managing corrections: an invoice that was not accepted is resent with the same identifier after the error is fixed, and an invoice that was accepted is corrected only by a return invoice.
Consumer price: a special case that changes the tax base
The latest version of the technical guide added the concept of a consumer price, the final price used as the tax base. It is sent at line level and must be equal to or greater than the unit price. It carries three constraints that make it a source of second-kind errors if misused:
- The permission is granted on request, through an electronic transaction the taxpayer files to activate it. It is not available automatically.
- It is available only to taxpayers registered for general sales tax or special sales tax.
- It applies to all lines of an invoice, so it cannot be used for some goods and not others.
The consumer price does not need to be shown to the buyer; it is an internal tax-calculation mechanism. But if it is entered below the unit price, used without permission, or applied to only some lines, the result is either a rejected invoice or an incorrect tax base, and neither is fixed by a partial return.
What the system requires of your records before you ever need a return
The Income and Sales Tax Department publishes ten operating instructions for integration, and roughly half of them relate directly to your ability to correct later. Taken together, they mean your accounting records must carry more than the invoice value:
- Storing the identifiers: the invoice number, the unique identifier, the QR code, and the invoice status. Those four together are what allows an invoice to be retrieved and referenced in any later return.
- Keeping the line number from the original sale, because returns are matched on it line by line.
- Resending with the same identifier on failure or timeout, without generating a new one.
- A full audit trail of every send, response, and resend.
- Logging errors in detail internally while showing the end user a simplified message.
There is one more element many overlook: the invoice counter. The invoice carries an additional document reference storing a counter value, an integer starting at one and incrementing. The counter sequence is part of the invoice’s identity in the system, and any gap or duplication in it complicates matching later.
The same applies to the income-source sequence, the activity identifier entered in the activity node. A wrong value there is among the most common causes of an internal server error, and that error blocks acceptance outright, so no return applies to it.
Why this is an accounting question, not only a technical one
A return invoice is not a tax document floating in isolation. It is a complete accounting event that creates a journal entry reversing the original sale in whole or in part, and updates the customer balance and inventory at the same time.
If the original invoice was on credit, the return reduces the accounts-receivable balance, which feeds through to your receivables turnover and to how you read collection quality. Numerous returns recorded incorrectly show receivables higher than they really are, making collections look worse than they are.
This is why managing corrections apart from the books is a double source of error: a tax document in the system with no matching entry in the books, or an entry in the books with no matching document in the system. Both surface at audit. Looking at the order-to-cash cycle as a whole, from sales order to invoice to collection to return, is what keeps the document and the entry aligned automatically instead of reconciling them by hand at month end.
What this means in daily operations
Three practical consequences follow from the above:
- Pre-send validation is not a luxury. As long as a correction costs an extra document in your tax record, every check before sending saves work later.
- Storing identifiers is effectively mandatory. The invoice number, the unique identifier, every line number, the QR code, and the invoice status. Without them you cannot issue a valid return later.
- Manual entry doubles the cost. When invoices are keyed in by hand, errors in names, numbers, and rates recur, and each one consumes two documents to fix.
If you are not sure your business is ready for this full cycle, use the JoFotara readiness check to find the gaps before they show up in a rejected invoice. To confirm whether the obligation applies to you at all, see who must use e-invoicing in Jordan.
How Qoyod handles the correction cycle for you
The point of understanding these rules is not to apply them by hand, but to know what happens under the hood. Qoyod’s accounting software, integrated with the National Invoicing System, takes care of this layer:
- It builds the invoice file to the UBL 2.1 standard and sends it to the system, then stores the invoice number, its unique identifier, its status, and the QR code automatically.
- It creates the return invoice already linked to the original, with the correct reference and the return reason, and matches lines on their original numbers.
- It blocks returns that would exceed the quantity sold, and allows multiple partial returns until the quantities are exhausted.
- It retries a failed send with the same unique identifier, so invoices are not duplicated in your record.
- It reflects the return in the journal entries and in inventory and customer balances at the same time, not as a separate step.
One point for accuracy: Qoyod does not edit an issued invoice, because the system does not permit that for any provider. What it does is manage the official correction path correctly and keep it connected to your books, instead of leaving you to run it by hand and mislink the documents.
Where to go after this guide
We covered a single question here: editing an issued invoice and its official alternative. To complete the picture, continue with the neighbouring topics:
- Mandatory fields: what the invoice must carry before sending, in e-invoicing requirements in Jordan.
- Verifying an issued document: how the QR code is checked, in verifying an e-invoice with the Sanad app.
- Tax rates and categories: the accepted rates and how they are calculated, in general sales tax in Jordan.
- General questions about the system: in the frequently asked questions.
Frequently asked questions
Can an invoice already sent to the National Invoicing System be edited?
No. The technical integration guide defines no edit operation for an issued invoice. The system defines only two types: a new invoice with value 388, and a return invoice with value 381. Correction happens by issuing a return invoice that references the original.
Is there a debit note in the National Invoicing System?
No. The guide defines only the return invoice, which is legally a credit note. There is no debit note document type, so no procedure should be built on one.
How do I correct a buyer name I typed incorrectly?
Buyer data on a return invoice is a fixed description that is not changed, and returns are based on quantities rather than on data. The practical path is therefore to return the invoice in full and issue a new one with the correct details.
Can a return exceed the value of the original invoice?
No. Returns are on quantities only, and cannot exceed the quantity sold on the original invoice. Multiple partial returns against the same invoice are allowed until the quantities are exhausted.
What do I need to store so I can issue a return later?
The original invoice number, its unique identifier, its total value, and each line number in it. The line number matters in particular, because returns are matched on it. Storing the QR code and the invoice status is also recommended.
What does an ALREADY_SUBMITTED response mean?
It means you sent an invoice with the same number and the same unique identifier again, so the system returned the original QR code without creating a second invoice. This is the documented way to recover a code you did not store, not an edit operation.
Is a reason for the return mandatory?
Yes. The return reason is mandatory and is entered as free text on the return invoice, together with the payment means code designated for returns. A return invoice without a reason is incomplete.
