Native Zoho Integration

both2026-09-01

The native Zoho integration is one of POP’s sending channels (like SdI via POP, PEPPOL, KSeF): it syncs a document directly to Zoho Invoice or Zoho Books via OAuth, without going through a user-managed n8n webhook. It is a separate channel from the generic connector, which instead forwards the payload to an n8n webhook that you configure and manage yourself — use this page if you need direct sync, the other one if you want to route through your own n8n workflow.

Endpoint

GET /wp-json/api/v2/integration/zoho/status — connection status (region, product, org ID, token expiry, default invoice status, auto-create contacts).
POST /wp-json/api/v2/integration/zoho/sync — syncs a document to Zoho.
GET /wp-json/api/v2/integration/oauth/callback — OAuth callback used during authorization (handled automatically by the connection flow, not meant to be called manually).

What you need

the Zoho channel activated from the POP account panel (it is one of the mutually exclusive sending channels: activating it automatically deactivates the others).
completed OAuth authorization — the connected state in integration/zoho/status must be true before you can sync.
No paid plan required on WordPress, direct API, n8n, or MCP: syncing uses available credits. On Shopify, the Basic plan or higher is still required.

Good to know

every document synced in live mode consumes 1 credit.
zoho_product indicates whether the account is linked to Zoho Invoice or Zoho Books.
zoho_create_contact_if_missing controls whether a missing Zoho contact is created automatically during sync, instead of failing.
payment_terms is derived automatically from payment_data.payment_due_days.
Fiscal/payment metadata with no dedicated Zoho field (nature, ref_normative, and key payment_data values) is automatically copied into the Zoho invoice notes.
To map those same values onto Zoho custom fields instead, pass integration.custom_fields_map (an object with label or customfield_id per field) — the native integration only creates documents, it doesn’t update existing Zoho contacts.
Credit notes — require the linked order to already have a successfully synced Zoho invoice; without that reference the request fails with a 422 error (“Zoho credit notes require a Zoho parent invoice reference on the original order.”).
Sandbox — a request with environment: sandbox doesn’t create anything in Zoho: it returns a success response with a dry-run confirmation, without touching the real Zoho account.

Common errors

Code	Cause
`no_connector_configured`	No native connector active on the account
`unsupported_doc_type`	`doc_type` is not `TD01`/`TD04`
`missing_connected_invoice`	Credit note request missing `connected_invoice_data.id`
`tax_not_found`	An `order_items[].rate` value isn’t configured in Zoho
`contact_not_found`	Customer not found and auto-create is disabled
`contact_ambiguous`	Multiple Zoho contacts match the same VAT/email/name
`zoho_region_not_configured` / `zoho_organization_not_configured`	Region or Organization ID missing in account settings
`zoho_api_error`	Generic Zoho-side error forwarded by POP

For activation from the account panel and the status shown in the plugin/app, see integrations/zoho.