Zoho Books and Stedi integration

What moves between them

The primary flow runs both directions. Outbound: Zoho Books invoices and bills become Stedi 810 EDI documents, and Zoho Books purchase orders become 850 EDI documents, sent to trading partners via the Stedi connection configured per partner. Inbound: Stedi webhooks push parsed inbound EDI documents back as JSON, which ml-connector maps to invoice or bill records in Zoho Books based on document type. The integration runs on a schedule you control for outbound pushes; inbound documents arrive immediately as Stedi webhooks fire.

How ml-connector handles it

ml-connector stores the Zoho Books OAuth2 credentials (client ID, client secret, refresh token, and organization ID) encrypted and uses them to obtain fresh access tokens proactively before the 1-hour expiry. It stores the Stedi API key encrypted and includes it on every request. For each outbound document, ml-connector generates a unique Idempotency-Key and includes it in the Stedi request header to ensure that network retries do not duplicate EDI files. On the Zoho side, it respects the region field returned at authentication time and routes all API calls to the correct regional base URL. It maps Zoho Books invoice and bill line items to EDI segments with the correct commodity codes and quantities, and handles Zoho's multi-currency exchange_rate field by converting amounts to the transaction currency. For inbound EDI, it parses the Stedi webhook payload, identifies the document type (810 or 850), and creates or updates the matching Zoho Books record, linking it back to the Stedi Partnership and Connection for audit. Rate-limit handling on the Zoho side includes 429 backoff; on the Stedi side it waits for the Idempotency-Key to deduplicate if a prior request is still processing. Every record carries a full audit trail and can be replayed if a mapping or delivery error occurs.

A real-world example

A mid-market wholesaler runs Zoho Books for accounting and manages invoices and purchase orders for a network of distributors and suppliers. Before the integration, the accounting team exported invoices from Zoho Books and manually created X12 EDI 810 files using legacy EDI software, then uploaded them to each distributor's SFTP server. Purchase orders arrived from suppliers as EDI 850 files, which the team downloaded, manually mapped to Zoho, and re-entered to avoid errors. With Zoho Books and Stedi connected, every invoice posted in Zoho Books automatically translates to an EDI 810 document and routes to the correct distributor via Stedi within minutes, and inbound purchase orders from suppliers arrive as EDI 850 files, parse automatically, and create new bill records in Zoho Books with vendor names and line items pre-populated. The manual file transfer and re-keying step is gone, and the accounting team's month-end close is cleaner because supplier invoice and PO data is already synchronized.

What you can do

• •Send Zoho Books invoices and bills as EDI 810 documents to trading partners via Stedi SFTP, FTPS, or AS2 connections.
• •Send Zoho Books purchase orders as EDI 850 documents and receive inbound EDI 850 or 855 documents from suppliers, automatically creating or updating bill records.
• •Handle Zoho Books region-specific OAuth2 authentication and proactively refresh access tokens before the 1-hour expiry window.
• •Assign unique Idempotency-Keys to every Stedi outbound API call to prevent duplicate EDI files from network retries or replay.
• •Parse inbound EDI documents from Stedi webhooks and create invoice, bill, or purchase order records in Zoho Books with full audit linking and error replay capability.

Questions

Which direction does data move between Zoho Books and Stedi?

Both directions. Zoho Books invoices, bills, and purchase orders translate to X12 EDI documents and route to trading partners via Stedi. Inbound EDI documents from partners arrive through Stedi webhooks, parse into JSON, and create or update matching records in Zoho Books. The outbound flow runs on a schedule you configure; inbound flow is real-time as webhooks arrive.

How does ml-connector handle Zoho Books regional base URLs and OAuth2 refresh tokens?

ml-connector stores the OAuth2 credentials (client ID, client secret, and refresh token) encrypted and uses them to obtain fresh access tokens proactively before the 1-hour expiry. The region field returned in the token response tells ml-connector which regional base URL to use for all subsequent API calls. It caches this region per customer and routes all Zoho Books requests to the correct URL.

What prevents duplicate EDI files if a Stedi outbound request is retried?

ml-connector generates a unique Idempotency-Key for every Stedi API write and includes it in the request header. Stedi deduplicates requests using this key for 24 hours, so network retries or automated replays do not create duplicate EDI files.