Key Takeaways
4 insights · 11 min readA FAILED Zoho Books e-invoice was never delivered. Fix the data and push again; nothing needs to be cancelled.
VAL0001 errors name empty buyer fields: BillToLegalRegNo is the customer's licence number, BillToLegalAgency its issuing authority.
VAL1238 means a service code is not tagged as SAC. Services use SAC codes, goods use HSN codes.
Zoho surfaces errors in layers, so one test invoice took 3 push attempts. Clean all master data before go-live, not invoice by invoice.
When a Zoho Books e-invoice shows FAILED, open the reasons and read the VAL codes. VAL0001 BillToLegalRegNo and BillToLegalAgency mean the customer's Buyer ID Value and Buyer ID Authority are empty; VAL1238 means the item's code is not tagged as SAC. Fix those records, then push again.
In this guide
What FAILED meansOur case, step by stepVAL0001 BillToLegalRegNoBillToLegalAgencyVAL1238 SAC schemeWhy errors appear one at a timePre-push checklistPeppol ID formatPush Initiated vs PushedTesting with real invoicesFix it yourself or get help?DeadlinesA Zoho Books e-invoice failed status is the most common thing UAE businesses will see in the first weeks of e-invoicing, and the on-screen message rarely tells you what to fix. We hit it ourselves while implementing Zoho Books e-invoicing for a free zone services client: a deliberately tiny test invoice of AED 1.05 failed, failed again with three new errors, and only then moved to Push Initiated. This guide walks through what each error meant, where the fields live in Zoho Books, and the checklist we now run before any client's first push. It sits alongside our broader guide to UAE e-invoicing implementation.
BillToLegalAgency (authority) · Part 3
What does e-Invoice Status FAILED mean in Zoho Books?
A FAILED status means the invoice was rejected at validation and never reached your customer. Nothing was delivered over Peppol, so there is nothing to reverse; you correct the data and push again.
Full guide: Part 1: what “incomplete information or issues with PEPPOL network” really means in Zoho Books
Zoho Books shows each e-invoice's journey as a status on the invoice: Yet to be Pushed when it exists only in your books, Push Initiated once it has passed validation and been handed to the network, Pushed when delivery completes and a UUID is generated, and Failed when something stopped it. The first FAILED message we saw was entirely generic: the invoice could not be sent because of incomplete information or issues with the Peppol network, with a note to contact Zoho support.
That wording sends people looking for a network outage. In practice, almost every failure in early implementations is a data problem: a field the UAE PINT-AE standard requires that your Zoho Books records do not yet hold. The useful information is in the reason lines underneath, which list validation codes such as VAL0001 and VAL1238 when Zoho can identify them.
⚠️ Don’t mark a failed invoice as sent
Zoho Books may still show the invoice as Sent by email. That does not mean the e-invoice was delivered. Until the e-invoice status reads Pushed with a UUID, treat it as undelivered. See how our Zoho implementation tests this before go-live →
What happened when our client's Zoho Books e-invoice failed?
Our test invoice failed twice for different reasons before it pushed. The sequence below is anonymised, but the error codes are exactly as Zoho Books displayed them.
| Attempt | What Zoho Books showed | What it actually meant |
|---|---|---|
| 1 | FAILED: incomplete information or issues with Peppol network | A required field was missing. Zoho support pointed to the service line item having no SAC code. |
| 2 | FAILED: VAL0001 BillToLegalRegNo must not be empty; VAL0001 BillToLegalAgency[0].AgencyName must not be empty; VAL1238 Invalid ServiceCodeScheme | Two customer fields were empty, and the newly added service code was not tagged with the SAC scheme. |
| 3 | PUSH INITIATED: once successfully pushed, a UUID will be generated | Validation passed. The invoice was handed to the Peppol network. |
Two lessons came out of this straight away. First, the supplier side was not the problem: the organisation's legal name, TRN and Peppol address were already correct. Every error sat in the customer record or the item record, which is where most UAE ledgers are weakest. Second, fixing the one field support identified did not finish the job; it simply revealed the next layer of errors.
How do you fix VAL0001 BillToLegalRegNo must not be empty?
VAL0001 BillToLegalRegNo means the customer's legal registration number is empty. In Zoho Books it is the Buyer ID Value on the customer record, which for a UAE company is normally its trade licence number.
Full guide: Part 2: Zoho BillToLegalRegNo error, identifier types and bulk fixes
PINT-AE requires every buyer to be identified by a legal registration, not just a TRN. The TRN identifies the customer for VAT; the legal registration identifies the legal entity. Zoho Books keeps them in different places, which is why a customer with a perfectly correct TRN can still fail. To fix it:
- Open the customer — Sales › Customers, then edit the customer named on the failed invoice.
- Go to Other Details — this tab holds the e-invoicing identity fields: TIN, Buyer ID Value, Buyer ID Authority, legal name and electronic address.
- Enter the Buyer ID Value — the licence number exactly as printed on the customer's trade licence. For an individual buyer, use the identifier type that applies, such as an Emirates ID or passport.
- Save and push again — the field applies to every future invoice for that customer.
Ask customers for a copy of their trade licence when you onboard them. A licence copy gives you the licence number, the issuing authority and the legal name in one document, which covers three of the fields that fail most often.
How do you fix BillToLegalAgency AgencyName must not be empty?
BillToLegalAgency[0].AgencyName means the authority that issued the customer's licence is missing. In Zoho Books this is the Buyer ID Authority field, directly beside the Buyer ID Value.
Full guide: Part 3: Zoho BillToLegalAgency error, which authority to enter and how to audit it
The licence number on its own is ambiguous, because DET and every free zone issue their own numbers. The authority tells the network which register the number belongs to. For a Dubai mainland company that is typically the Department of Economy and Tourism (DET); for a free zone company it is the free zone authority that issued the licence, such as IFZA, DMCC, RAKEZ or Meydan. Our test customer was an FZ-LLC, so the correct entry was its free zone authority, not DET.
This is one of the easiest errors to get wrong at scale. Teams copy “DET” onto every customer, and free zone customers then fail or carry incorrect data. Check the licence itself rather than guessing from the company name or address.
Stuck on a FAILED Zoho Books e-invoice?
Send us the error codes on WhatsApp. We’ll tell you which records to fix, or clean them for you as part of a fixed-fee implementation.
How do you fix VAL1238 Invalid ServiceCodeScheme in Zoho Books?
VAL1238 Invalid ServiceCodeScheme means a line item has a service code that is not tagged as a SAC code. When a service code is provided, PINT-AE requires its scheme to be SAC.
Full guide: Part 4: Zoho VAL1238, goods vs services, SAC vs HSN and unit codes
This error appeared only after we had added a code to the service item, which is what makes it confusing: the code was there, but Zoho Books was not sending it under the SAC scheme. The usual causes are an item classified as goods when it is a service, or a code entered in the HSN field instead of the SAC field. To fix it, open Items, edit the item on the failed invoice, confirm the item type is Service, and make sure the code sits in the SAC field. Goods take HSN codes; services take SAC codes. Mixing them is one of the most common item-level failures.
While you are in the item, check the unit code too. UAE e-invoicing uses UN/CEFACT unit codes, such as H87 for a piece. A free-text unit like “nos” or “job” is the next error waiting to happen.
Why does Zoho Books show e-invoice errors one at a time?
Zoho Books shows errors one at a time because validation runs in layers. Once one blocking problem is found it is reported, and the checks behind it may not run until that problem is fixed.
That is why our first failure showed one generic message and the second showed three specific ones. It also explains a pattern you will see in support tickets: support identifies one missing field, you fix it, and a new set of errors appears. Nobody is withholding anything; the validator simply had not reached those checks yet.
The practical response is to stop fixing invoice by invoice. Run a full master-data check across every active customer and item before the first live push, using the checklist in the next section. Our client's test needed three push attempts for one customer and one item. A business with 80 customers and 40 items discovering its gaps this way would spend weeks on it.
✗ Fixing as errors appear
Push, fail, fix one field, push again. Each customer and item only gets fixed when an invoice for it fails, so failures keep surfacing for months and every fix waits on a support ticket.
✓ Cleaning master data first
Check every active customer and item against the required fields before go-live, then push one test per VAT scenario. Failures after go-live become rare and easy to trace.
Which fields must be complete before a Zoho Books e-invoice will push?
A Zoho Books e-invoice will only push when the organisation, the customer, the item and the invoice line all carry their required data. This is the checklist we now run before every client's first push.
| Level | Field to check | Typical symptom if wrong |
|---|---|---|
| Organisation | Legal name, 15-digit TRN, address with emirate, Zoho appointed as ASP in EmaraTax with status Linked | Nothing pushes for any customer |
| Customer | Legal name as on licence, TIN / TRN, tax treatment | Buyer identity errors |
| Customer | Buyer ID Value (licence number) | VAL0001 BillToLegalRegNo |
| Customer | Buyer ID Authority (DET or free zone authority) | VAL0001 BillToLegalAgency AgencyName |
| Customer | Electronic address (Peppol ID 0235:TIN) | Customer not found on Peppol; invoice not delivered |
| Item | Goods or service type, HSN (goods) or SAC (services) code | VAL1238 Invalid ServiceCodeScheme |
| Item | UN/CEFACT unit code, VAT treatment | Unit or tax category errors |
| Invoice line | Correct VAT category per line (standard, zero-rated, exempt, out of scope) | Tax category or total mismatch |
Two of these sit outside Zoho Books. The EmaraTax ASP appointment has to show Linked, not just Submitted. And customers must be registered on the network to receive e-invoices, which in the UAE means they have appointed their own accredited service provider.
What is the correct Peppol ID format, and how does it go wrong?
A UAE Peppol participant ID is 0235, a colon, and the first 10 digits of the 15-digit TRN, for example 0235:1234567890. The 10 digits are the TIN; 0235 identifies the UAE scheme.
The format is simple, which is exactly why typing it by hand goes wrong. In our own support ticket the supplier Peppol ID was typed with extra digits, even though the ID Zoho Books printed on the invoice was correct. The system had it right; the human copy did not. Had that mistyped ID been entered on a customer record instead, invoices to that customer would have gone to an address that does not exist.
Two habits prevent this. Derive the ID from the TRN rather than asking customers to send it, and copy it from the TRN on the customer's VAT certificate, never from an email signature. Then compare the electronic address shown on a test invoice against the certificate before going live.
What do PUSH INITIATED and Pushed mean after you fix the errors?
Push Initiated means the invoice passed validation and is on its way; Pushed means delivery completed and a UUID was generated. Only Pushed is the finish line.
After our third attempt, Zoho Books showed Push Initiated with the note that a UUID would be generated once the push succeeded. Record the UUID once it appears; it is your proof the e-invoice was delivered and reported. From that point the invoice is locked. If anything on it is wrong, you correct it with a credit note referencing the original invoice, not by editing.
Expert Tip
Train whoever raises invoices to check the e-invoice status column daily for the first month. A single failed invoice sitting unnoticed for a week is a customer who has not received a valid invoice, and a payment that has not started its clock.
Is it safe to test Zoho Books e-invoicing with a live invoice?
Testing with a live invoice is acceptable, but a pushed test invoice is a real tax invoice reported through the system. Plan the reversal before you send it.
That is why our test was for AED 1.05. Here is how the numbers work for a test like this, and what the implementation itself costs:
| Item | Calculation | Amount |
|---|---|---|
| Test invoice value | Service fee | AED 1.00 |
| VAT on test invoice | AED 1.00 × 5% | AED 0.05 |
| Test invoice total | AED 1.00 + AED 0.05 | AED 1.05 |
| Credit note to reverse it | Full reversal if no real supply was made | (AED 1.05) |
| Net VAT effect | AED 0.05 − AED 0.05 | AED 0.00 |
| Fastlane Zoho implementation | AED 499 + 5% VAT (AED 24.95) | AED 523.95 |
Only test with a customer who has agreed to receive the test, and push a credit note through the same route so the reversal is also evidenced. If the test reflects a genuine supply, there is nothing to reverse: it simply becomes your first live e-invoice.
Should you fix Zoho Books e-invoice failures yourself or get help?
You can fix a handful of Zoho Books e-invoice failures yourself with this guide. Get help when you have more than a few customers, mixed goods and services, free zone customers, or more than one person raising invoices.
With five or fewer customers, one VAT treatment and clean data, the fixes above take an afternoon. Beyond that, the work is mostly master data: collecting licence copies, assigning authorities, classifying items, and testing one invoice per VAT scenario you actually use. That is what our Zoho Books e-invoicing implementation service covers for AED 499 + VAT per organisation, including ASP appointment, test invoices with recorded UUIDs, a 30-minute live staff training session and go-live sign-off. Fastlane is an Authorized Zoho Partner and FTA-registered Tax Agent, so the same team configures Zoho and checks the VAT treatment behind each invoice.
If you are not yet sure Zoho Books is the right route, start with our free diagnosis on the UAE e-invoicing page, or compare providers in our UAE ASP comparison.