Overview

This guide describes how Zoho Books and the wider Zoho Finance / Zoho One ecosystem connect to TrustBill, a UAE FTA-accredited service provider (ASP), so Zoho users can issue PINT-AE compliant e-invoices without leaving Zoho.

Zoho Books UAE edition already handles VAT, TRN, and VAT201 filing. It does not ship with native Peppol / PINT-AE e-invoicing. TrustBill sits between Zoho and the FTA: invoices are pushed from Zoho Books via the Marketplace app (or webhooks / Deluge / Zoho Flow), translated to PINT-AE XML, validated in real time, delivered over the Peppol network via a certified ASP (Tron-Stride or Storecove), and the FTA acknowledgement is written back into a custom field on the Zoho invoice.

What this integration delivers

Native Zoho Marketplace app — installed with two clicks, no code
OAuth 2.0 authentication — no API keys stored inside Zoho
Sales invoices, credit notes and recurring invoices all mapped to PINT-AE document types
UAE VAT treatments (Standard 5%, Zero-Rated, Exempt, Reverse Charge, Designated Zone) mapped to FTA tax categories automatically
Live FTA status written back into custom fields on the Zoho invoice (TrustBill Status, TrustBill Ack Ref)
Bulk migration for historical Zoho invoices via CSV
Works with Zoho Books multi-organization setups (one Zoho org per TRN)
Compatible with Zoho Flow, Zoho CRM and Zoho Inventory as upstream sources

Supported Zoho Products & Editions

Zoho Books is the system of record for VAT and invoicing. Every other Zoho app in the list below is supported through Zoho Books — an invoice created in CRM, Inventory or Commerce lands in Books, and Books is what TrustBill reads.

Zoho product	Role in the flow	Support level
Zoho Books (UAE edition)	System of record — invoices, VAT, TRN, VAT201	Full — primary integration surface
Zoho Invoice	Standalone invoicing (no VAT ledger)	Supported — recommend migrating to Zoho Books for UAE VAT compliance
Zoho Inventory	Sales orders → Books invoices	Full — TrustBill reads from Books after the order is invoiced
Zoho Billing (formerly Subscriptions)	Recurring / subscription invoices synced to Books	Full — see Recurring Invoices
Zoho CRM	Quotes / Sales Orders → Books invoices	Full — via Zoho CRM ↔ Books sync
Zoho Commerce	E-commerce orders → Books invoices	Full — via Zoho Commerce ↔ Books sync
Zoho Expense	Vendor bills / reimbursements → Books	Supported for purchase-side e-invoicing
Zoho Finance Plus	Bundle (Books + Inventory + Billing + Expense + Checkout)	Full — all components covered
Zoho One	Full suite — includes all of the above	Full — TrustBill Marketplace app is Zoho One compatible
Zoho Flow	No-code automation between Zoho apps and TrustBill	Full — TrustBill Flow connector available

Zoho Books UAE edition is required. The connector reads tax treatments, TRN and VAT rates that only exist on the UAE-localised edition. If your Zoho Books organization is set to a different country, switch it to Settings → Organization → Country of Operation = United Arab Emirates before installing the connector (this can only be done at organization creation on new Zoho Books orgs).

Data Center & Residency

Zoho does not (yet) host data in the UAE. The TrustBill Marketplace app works across all Zoho data centers, and TrustBill stores the invoice data in the UAE (AWS me-central-1) once it reaches our platform.

Zoho DC	Domain	Recommended for UAE?
Zoho India	books.zoho.in	Yes — closest DC, lowest latency to UAE
Zoho Saudi Arabia	books.zoho.sa	Yes — GCC region
Zoho EU	books.zoho.eu	Supported
Zoho US	books.zoho.com	Supported
Zoho Australia	books.zoho.com.au	Supported
Zoho Japan / China / Canada	books.zoho.jp / com.cn / ca	Supported

The Marketplace app auto-detects your Zoho DC from the OAuth handshake and points to the correct region-specific Zoho Books API base URL (e.g. https://www.zohoapis.in vs https://www.zohoapis.com). No manual configuration required.

Prerequisites

On the Zoho side

An active Zoho Books UAE organization with Settings → Taxes → VAT enabled
Valid 15-digit UAE TRN saved at Settings → Organization → VAT Registration Number
Contacts populated with a TRN (for B2B), country, billing address and correct Tax Treatment
Tax rates configured: Standard Rate (5%), Zero Rate (0%), Exempt (—)
Admin-level Zoho user (only an Admin can install a Marketplace app)
Optional: Zoho Flow subscription if using the no-code path

On the TrustBill side

A TrustBill SME account (one account = one TRN = one Zoho Books organization)
Completed KYB (business verification) — trade licence + TRN certificate uploaded
Submission mode set to test or sandbox during onboarding, live for production
OAuth client credentials are provisioned automatically when you install the Marketplace app; no manual API key needed

Integration Architecture

The Zoho ↔ TrustBill integration is event-driven where possible (Zoho webhooks) and falls back to polling only for status write-back.

Outbound flow (Zoho Books → TrustBill → FTA)

An invoice moves to status Sent in Zoho Books (draft invoices are not pushed).
Zoho fires the invoice.sent webhook (registered by the Marketplace app during install).
TrustBill's Zoho webhook receiver fetches the full invoice + line items + contact via the Zoho Books REST API, using the OAuth access token.
Payload is translated into TrustBill's InvoiceCreateInput shape.
TrustBill calls its own POST /v1/invoices internally — stored as draft.
If auto-submit is enabled on the TrustBill tenant, POST /v1/invoices/submit fires immediately; otherwise a TrustBill operator can review first.
Pipeline runs: queued → transformed → validated → delivered (PINT-AE XML built, Schematron-validated, handed to the ASP).
ASP forwards the XML to the FTA over Peppol.

Inbound flow (FTA → TrustBill → Zoho Books)

The ASP posts an inbound webhook to TrustBill when the FTA acknowledges or rejects the invoice.
TrustBill verifies the ASP's HMAC signature and updates the status to acknowledged or rejected.
TrustBill's Zoho worker calls PUT /invoices/{id} to update the custom fields cf_trustbill_status and cf_trustbill_ack_ref on the Zoho invoice.
Zoho users see the status in the invoice list view (once you add the custom fields to the column layout).

Connection Methods

Six ways to connect Zoho to TrustBill, ordered from easiest (no-code) to most flexible (custom):

1. Zoho Marketplace App (recommended)

Install TrustBill E-Invoicing for Zoho Books from the Zoho Marketplace. OAuth 2.0 handshake, custom fields auto-created, webhooks auto-registered, custom button added to the invoice screen.

No code, no server, no keys to manage
Works on all Zoho DCs (US/EU/IN/SA/AU/JP/CA/CN)
Adds a Submit to FTA button on every invoice
Adds a TrustBill widget on the invoice sidebar showing FTA status + timeline
Compatible with Zoho One / Zoho Finance Plus bundles

2. Zoho Webhooks (direct)

If you cannot install a Marketplace app (e.g. locked-down org), register the TrustBill webhook manually at Settings → Automation → Webhooks. Point it at your TrustBill tenant's dedicated Zoho webhook URL.

Send full JSON payload on invoice.sent, invoice.updated, creditnote.created
Add a Zoho Workflow Rule as the trigger (e.g. "when Invoice Status becomes Sent")
TrustBill signs its inbound webhooks with HMAC-SHA256; verify in your Zoho workflow if you loop back

3. Deluge Custom Function

Write a small Deluge script attached to a Zoho Books workflow. The script calls the TrustBill REST API directly when an invoice is marked Sent.

Best when you need custom logic (e.g. skip certain customers, transform line notes)
You manage the OAuth token / API key inside Zoho's Secret Store
Use invokeUrl with the TrustBill Bearer JWT
Sample Deluge snippet available from TrustBill support

4. Zoho Flow (no-code)

TrustBill publishes a Zoho Flow connector — drag-drop a "New Zoho Books invoice → Create TrustBill invoice → Submit" flow in minutes.

Best for orgs that already standardise integrations on Zoho Flow
Includes retry, error branching, and Slack / email notification on failure
Works across Zoho apps — e.g. Zoho CRM Quote → Books Invoice → TrustBill in one flow

5. CSV Export

Export invoices from Sales → Invoices → Export and upload the file to TrustBill's bulk import endpoint. Best for one-off historical migrations.

Zero technical setup
Runs through TrustBill's POST /v1/invoices/bulk — up to 1,000 rows / 5 MB per file
See Bulk Migration

6. Upstream: Zoho CRM / Inventory / Commerce

Sales orders or quotes originating in CRM, Inventory or Commerce sync to Books as invoices via Zoho's built-in module sync. TrustBill still reads from Books — no separate connector required.

Zoho CRM → Books: enable Sync Setup → Sales Order → Invoice
Zoho Inventory → Books: automatic when both apps use the same organization
Zoho Commerce → Books: enable Settings → Integrations → Zoho Books

Which method should I use?

For 95% of Zoho Books UAE customers, install the Marketplace app. Use Zoho Flow if you already standardise on it. Use Deluge only if you need custom logic (e.g. exclude specific customer groups). Use webhooks only when the Marketplace app is blocked by your Zoho admin policy.

Authentication (OAuth 2.0)

The Zoho side uses OAuth 2.0 authorization code flow. The Marketplace app requests these scopes on install:

ZohoBooks.invoices.READ
ZohoBooks.invoices.UPDATE      (for write-back)
ZohoBooks.creditnotes.READ
ZohoBooks.contacts.READ
ZohoBooks.settings.READ         (tax rates, organization)
ZohoBooks.settings.CREATE       (create custom fields on install)
ZohoBooks.customviews.CREATE    (add TrustBill view to invoice list)

TrustBill stores only the refresh_token. Access tokens are minted on demand and cached in memory for their 60-minute lifetime.

The TrustBill side (internal, invisible to the Zoho user) uses Bearer JWT — the Marketplace app forwards Zoho payloads to the TrustBill API with a per-tenant JWT.

Idempotency-Key derivation for Zoho

Every TrustBill write endpoint requires an Idempotency-Key. For Zoho, derive it from the Zoho invoice ID (stable across renumbering):

Idempotency-Key: zoho::{organization_id}::{invoice_id}

Zoho webhook retries (up to 5) reuse the same key — TrustBill returns the cached response, no duplicate FTA submission.

Zoho Books → PINT-AE Field Mapping

The connector translates Zoho Books' JSON invoice shape into TrustBill's InvoiceCreateInput, which TrustBill then renders into PINT-AE XML.

Header-level mapping

Zoho Books field	TrustBill field	Notes
`invoice_number`	`number`	1–64 chars, unique per tenant + mode
`date`	`issueDate`	ISO YYYY-MM-DD (already Zoho's format)
`due_date`	`dueDate`	Optional
`currency_code`	`currency`	Must be `AED`; multi-currency invoices converted at Zoho's `exchange_rate`
`Organization.vat_reg_no`	`seller.trn`	15-digit UAE TRN (Settings → Organization)
`customer_name`	`buyer.name`	Contact display name
`Contact.tax_reg_no`	`buyer.trn`	15-digit TRN; leave empty for B2C contacts
`Contact.tax_treatment`	→ `buyer.taxScheme` hint	See VAT Treatment Mapping
`Contact.billing_address`	`buyer.address.{line1,line2,city,country}`	Country normalised to ISO 3166-1 alpha-2
`reference_number`	`sellerInvoiceReference`	Preserved for traceability
`notes` / `terms`	`notes`	Concatenated; visible in FTA-facing XML
`invoice_id`	Idempotency key	Used as `zoho::<org_id>::<invoice_id>`

Line-level mapping (line_items[])

Zoho Books field	TrustBill field	Notes
`name` / `description`	`lines[].description`	Uses `name`; falls back to `description`. Supports Arabic.
`quantity`	`lines[].quantity`	Must be > 0
`rate`	`lines[].unitPrice`	VAT-exclusive; connector strips VAT if `is_inclusive_tax = true`
`unit`	`lines[].unit`	Zoho unit code mapped to UN/ECE Rec 20 (Nos → C62, kg → KGM, hrs → HUR)
`tax_percentage`	`lines[].vatRate`	Zoho stores as percentage (5), connector converts to fraction (0.05)
`tax_treatment` / line `vat_treatment`	`lines[].taxCategory`	Mapped via the table in the next section
`discount`	`lines[].discountAmount`	Per-line discount, applied before VAT (Zoho's absolute or percent → connector normalises)
`item_id` / `sku`	`lines[].sellerItemId`	Preserved for traceability

Totals are computed server-side

Do not send subtotal / vat_amount / total. TrustBill re-computes totals from lines[] and returns them so Zoho can reconcile. If Zoho's total differs from TrustBill's by more than ±0.01 AED (usually a rounding-mode mismatch on inclusive-tax invoices), the connector logs a variance and blocks submission until the invoice is corrected in Zoho.

Create Invoice (draft)

Endpoint: POST /v1/invoices

A real Zoho Books invoice mapped to the TrustBill payload. Zoho invoice: INV-002194 — Sale of software licences to a Dubai buyer at 5% VAT.

Request body

{
  "number": "INV-002194",
  "issueDate": "2026-09-08",
  "dueDate": "2026-10-08",
  "currency": "AED",
  "invoiceType": "sale",
  "buyer": {
    "name": "Meraas Digital LLC",
    "trn": "100456789200003",
    "country": "AE",
    "email": "ap@meraasdigital.example",
    "address": {
      "line1": "The Greens, Building 7, Office 305",
      "city": "Dubai",
      "country": "AE"
    }
  },
  "seller": {
    "name": "Zoho Trader LLC",
    "trn": "100100100100007",
    "country": "AE"
  },
  "lines": [
    {
      "description": "Microsoft 365 Business Standard — Annual (5 seats)",
      "sellerItemId": "M365-BS-5",
      "quantity": 5,
      "unit": "C62",
      "unitPrice": 480.00,
      "vatRate": 0.05,
      "taxCategory": "standard_5"
    }
  ],
  "sellerInvoiceReference": "Zoho invoice_id 5f7a9c...",
  "notes": "Renewal — 30 days net"
}

Response (201 Created) — abbreviated:

{
  "id": "e4b1f9c0-....-uuid",
  "number": "INV-002194",
  "status": "draft",
  "invoiceType": "sale",
  "totals": { "subtotal": 2400, "tax": 120, "total": 2520, "currency": "AED" },
  "pipeline": [],
  "errors": [],
  "submissionMode": "sandbox",
  "source": "zoho-marketplace-app"
}

Credit Notes & Debit Adjustments

Zoho Books has a first-class creditnotes API. Debit adjustments on the purchase side are handled via vendorcredits or as expense adjustments — the connector maps both:

Zoho object	`invoiceType`	Required extra fields
Credit Note (applied to invoice)	`credit_note`	`referencedInvoiceNumber` = original invoice number, `reasonCode`
Vendor Credit / Debit Note (purchase side)	`debit_note`	`referencedInvoiceNumber` = original vendor bill number
Standalone Credit Note (no reference)	`credit_note`	`reasonCode` = `OtherAdjustment`

Sign convention: Zoho creditnotes carry positive quantities and positive rates. Send the same to TrustBill — do not negate. The invoiceType tells TrustBill and the FTA that the document reverses the reference invoice; PINT-AE handles the sign in the XML.

Recurring & Subscription Invoices

Zoho Books and Zoho Billing (formerly Subscriptions) generate child invoices from a recurring profile. The connector treats each generated invoice as a fresh event:

Zoho fires invoice.created and (once sent) invoice.sent for every generated child
Each child invoice gets its own invoice_id — so a fresh Idempotency-Key, a fresh TrustBill draft, a fresh FTA submission
The recurring profile itself is not pushed to TrustBill — only the concrete invoices it produces
For Zoho Billing subscriptions with pro-rated changes, ensure the invoice line description carries the pro-ration period (Zoho does this by default)

Auto-submit tip: for recurring invoices, enable TrustBill's auto-submit on ingest setting. Otherwise every child sits as a draft in TrustBill waiting for a human to click Submit — defeats the purpose of recurring.

Submit Invoice(s) for Delivery

Creating a draft in TrustBill does not deliver the invoice to the FTA. Submission is an explicit second call so a user can review before sending.

Endpoint: POST /v1/invoices/submit

{ "ids": ["e4b1f9c0-....-uuid"] }

Accepts 1–200 UUIDs per call. Non-draft invoices are silently skipped, so retry is safe.

Zoho Marketplace app UX: the app adds a Submit to FTA button on every Zoho invoice screen — one click, no need to jump to the TrustBill dashboard. Auto-submit-on-ingest is the default for tenants with more than 50 invoices/month.

Status Tracking & Custom Field Write-back

On install, the Marketplace app creates three custom fields on the Zoho Books Invoice module. Every TrustBill status change writes back to these fields via the Zoho Books API.

TrustBill status	Meaning	Zoho custom field written
draft	Created in TrustBill, not submitted	`cf_trustbill_status = Draft`
queued	Submitted, waiting for pipeline	`cf_trustbill_status = Queued`
validated	Passed schema + Schematron	`cf_trustbill_status = Validated`
delivered	Sent to FTA via ASP	`cf_trustbill_status = Delivered`
acknowledged	FTA confirmed receipt / validity	`cf_trustbill_status = Acknowledged`, `cf_trustbill_ack_ref = <FTA ref>`
rejected	FTA or ASP rejected the invoice	`cf_trustbill_status = Rejected`, `cf_trustbill_reject_reason = <code>`

Add the three custom fields to the invoice list column layout: Invoices → Column Layout → Add Column → cf_trustbill_status / cf_trustbill_ack_ref / cf_trustbill_reject_reason. You can then filter and colour-code by status directly inside Zoho.

Bulk Migration from Zoho Books

To migrate historical Zoho Books invoices (up to 12 months back) into TrustBill:

In Zoho Books: Sales → Invoices → filter by date range → Export → CSV
Run the TrustBill zoho-csv-normaliser script to remap Zoho's column headers to the TrustBill schema below
Upload in test mode via POST /v1/invoices/bulk
Review the summary; repeat in sandbox and live

TrustBill CSV column headers

number,issueDate,dueDate,invoiceType,currency,sellerTrn,sellerName,buyerTrn,buyerName,buyerCountry,buyerAddressLine1,buyerCity,lineDescription,lineQty,lineUnit,lineUnitPrice,lineVatRate,lineTaxCategory,referencedInvoiceNumber,notes

Limit	Value
Max rows per file	1,000 invoices
Max file size	5 MB
Multiple lines per invoice	Repeat the `number` column
Partial success	Yes — bad rows reported without rolling back the batch

Test / Sandbox / Live Modes

Every TrustBill tenant has one active submission mode. Invoices are hard-partitioned — a live invoice cannot be viewed from sandbox, and vice-versa.

Mode	Purpose	Reaches FTA?
`test`	Local integration testing — no ASP call	No
`sandbox`	End-to-end dry run against the ASP sandbox	FTA sandbox only
`live`	Real, legally binding e-invoicing	Yes — the FTA production network

Zoho best practice: keep the connector in sandbox for the full first VAT-return period. Reconcile TrustBill's "Delivered invoices" report against Zoho Books' Reports → Taxes → VAT Return before switching to live.

VAT Treatment Mapping

Zoho Books UAE captures the VAT scheme as tax_treatment on the contact and (optionally) as vat_treatment on the line. Map each Zoho treatment to a TrustBill taxCategory once, at connector setup:

Zoho `tax_treatment` / `vat_treatment`	`vatRate`	TrustBill `taxCategory`
`vat_registered`	0.05	`standard_5`
`zero_rated` (export)	0	`zero_rated_export`
`zero_rated` (healthcare)	0	`zero_rated_healthcare`
`zero_rated` (education)	0	`zero_rated_education`
`exempt` (financial)	0	`exempt_financial`
`exempt` (residential rent)	0	`exempt_residential_rent`
`designated_zones`	0	`reverse_charge_designated_zone`
`out_of_scope`	0	`out_of_scope`
`non_gcc`	0	`zero_rated_export`
`gcc_vat_registered`	0.05	`standard_5`
`gcc_vat_not_registered`	0	`zero_rated_export`

Where line-level vat_treatment exists, it wins over the contact-level default (this matches Zoho's own precedence rule). If a line has no explicit treatment and the contact treatment is unmapped, the connector flags the invoice and blocks submission.

UAE-Specific Scenarios

Free Zone / Designated Zone sellers

Set Settings → Organization → Free-Trade Zone = Yes. The connector propagates it as seller.designatedZone: true so PINT-AE emits the free-zone declaration correctly.

Margin scheme (used cars, antiques, second-hand goods)

Zoho Books does not have a built-in "margin scheme" flag. TrustBill's Marketplace app adds a per-item custom field cf_margin_scheme — when checked, the connector sends lines[].marginScheme: true and uses the item's Purchase Rate to compute the margin base.

Reverse charge on imports

Purchase invoices where the vendor tax_treatment = non_gcc and the line vat_treatment = "Purchase from Outside GCC — Reverse Charge" are mapped to invoiceType: "purchase" + taxCategory: "reverse_charge_designated_zone". TrustBill emits the required ReverseCharge markers.

B2C simplified tax invoices

Zoho contacts with no TRN and tax_treatment = non_gcc or vat_not_configured are treated as B2C. Invoices under 10,000 AED are simplified tax invoices under FTA rules; TrustBill emits the correct PINT-AE profile automatically.

Multi-organization Zoho Books

Each Zoho Books organization = one TRN = one TrustBill tenant. Install the Marketplace app once per organization. The app stores the mapping zoho_org_id → trustbill_tenant_id so you can run several TRNs from a single Zoho login.

Error Handling

TrustBill errors follow the shape { code, humanMessage, meta? }. The Marketplace app surfaces the humanMessage in the invoice sidebar widget and writes the code to cf_trustbill_reject_reason.

HTTP	Typical `code`	Zoho root cause	Action
400	`invalid_body`	Zoho contact missing TRN, or invoice line missing tax rate	Fix the contact / line in Zoho; the app auto-resubmits
400	`totals_mismatch`	Zoho inclusive-tax invoice rounded per-line; TrustBill rounded per-invoice	Set Zoho Settings → Preferences → Tax → Round-off preference to Total of the Invoice
400	`unknown_tax_treatment`	Custom tax treatment on the contact not in the connector's mapping	Add it in TrustBill Marketplace app → Settings → Tax Treatment Mapping
401	`zoho_oauth_expired`	Refresh token revoked (admin rotated it in Zoho)	Reconnect the Marketplace app in Settings → Integrations → TrustBill → Reconnect
403	`kyb_required`	TrustBill tenant not yet approved by compliance	Contact TrustBill support
409	`invoice_mode_mismatch`	Zoho is on live invoices but tenant still in sandbox	Switch mode in TrustBill dashboard
409	`invoice_number_duplicate`	Two Zoho orgs pushed the same invoice number	Use per-org numbering prefixes in Zoho Settings → Preferences → Invoices → Prefix
413	`bulk_payload_too_large`	CSV export > 1,000 rows or > 5 MB	Split by month and re-upload
422	`idempotency_required`	Custom Deluge script missed the header	Always send `Idempotency-Key` = `zoho::org::invoice_id`

Setup Checklist

Confirm Zoho Books org is UAE edition and Country of Operation = United Arab Emirates
Fill in Organization TRN and VAT registration date in Zoho Books settings
Confirm all UAE contacts have a tax_treatment and (for B2B) a valid 15-digit TRN
Create your TrustBill SME account and complete KYB (trade licence + TRN certificate)
Install the TrustBill Marketplace app in Zoho Books (Marketplace → TrustBill E-Invoicing → Install)
Approve the OAuth scopes requested by the app (must be a Zoho Admin)
Confirm custom fields cf_trustbill_status, cf_trustbill_ack_ref, cf_trustbill_reject_reason now exist on the Invoice module
Add the custom fields to the invoice list column layout
Enable sandbox mode in the TrustBill dashboard
Send a test invoice in Zoho Books — mark it Sent → confirm it reaches acknowledged in TrustBill within 3 minutes
Reconcile Zoho's VAT Return report against TrustBill's "Delivered invoices" report
Switch to live mode when FTA registration is complete

Suggested test cases before go-live

B2B invoice, single line, 5% VAT — expect acknowledged
B2C invoice under 10,000 AED, no TRN — expect PINT-AE "simplified" profile
Credit note applied to an earlier invoice — expect matching pair
Export sale (contact tax_treatment = non_gcc) — expect zero_rated_export
Designated-zone sale — expect reverse-charge markers
Multi-line invoice with mixed VAT rates (5% + 0%) — expect two taxCategory values
Recurring invoice child — expect fresh FTA submission per child
Inclusive-tax invoice — expect totals to match Zoho within 0.01 AED
OAuth token expiry — expect automatic refresh, no user action
Bulk upload of 500 historical invoices via CSV — expect partial success reported per row

Troubleshooting

Symptom	Likely cause	Fix
Marketplace app install fails	User is not a Zoho Admin	Log in as an Admin (Marketplace apps require org-wide scope)
Invoice sent in Zoho, nothing in TrustBill	Webhook rejected (Zoho retries 5× then gives up)	Check Settings → Automation → Webhook Logs in Zoho; look for 4xx responses
Custom fields don't appear	App scope missing `settings.CREATE`	Re-install with all requested scopes approved
Invoice stuck in `queued`	Insufficient TrustBill credit	Check the TrustBill dashboard banner; top up credit
Invoice reaches `rejected` with "buyer_trn_invalid"	Zoho contact TRN is 14 digits or has spaces	Fix in Zoho: Contacts → Edit → Tax Registration Number. Connector auto-retries.
Arabic descriptions render as `???`	Zoho line description was pasted from a legacy Windows-1256 source	Re-type or paste from a UTF-8 source; Zoho itself stores UTF-8
`totals_mismatch` on inclusive-tax invoices	Zoho's per-line rounding vs TrustBill's per-invoice rounding	Zoho: Settings → Preferences → Tax → Amount Rounding → Total of the Invoice
Duplicate FTA submissions after a network blip	Custom Deluge script forgot the Idempotency-Key	Use `zoho::org::invoice_id` derivation
Status write-back not appearing on Zoho invoice	OAuth scope missing `invoices.UPDATE`	Reconnect the Marketplace app and re-approve scopes

Support & Contact

Technical Support

WhatsApp: +971 52 260 9313
Email: info@trustbill.ae
Documentation hub: trustbill.ae/en/documentation
Zoho integration overview: trustbill.ae/en/integrations/zoho
Tally integration: /documentation/tally
Focus RT integration: /documentation/focus-rt
ERP Partner API guide: /documentation/erp-partner-api

Escalation

For go-live escalations, include your TrustBill tenant ID, the Zoho organization ID + invoice ID of the failing invoice, and the timestamp of the failed pipeline run. TrustBill support responds to Zoho-tagged tickets within one business hour during UAE working days.

Zoho Integration with UAE FTA E-Invoicing via TrustBill