How does ml-connector handle Toast's multi-location setup?

Toast requires a separate Toast-Restaurant-External-ID for each location. ml-connector retrieves all accessible locations via GET /partners/v1/restaurants, loops through each location ID, and sets the header on every request. Sales orders, payments, and labor data are retrieved per location and tagged with the location in Zoho Books for multi-location reporting.

What happens with voided orders and service charges flagged as gratuity?

Voided orders and checks are returned by Toast's API but must be filtered before posting to Zoho Books. ml-connector filters voided==true before creating invoices. Service charges may be classified as gratuity (gratuityServiceCharge:true), affecting tip and revenue recognition. ml-connector respects this flag and posts them correctly.

Why does ml-connector poll Toast nightly if webhooks are available?

Toast webhooks are not guaranteed delivery and do not cover payments or labor data. ml-connector uses webhooks where available for real-time notification but runs a nightly reconciliation poll via ordersBulk as a safety net to catch missed orders and ensure all payments and shifts are posted to Zoho Books.

Zoho BooksToast

Zoho Books and Toast integration

Restaurants use Toast for point of sale, ordering, and labor management, and Zoho Books for accounting and financial reporting. Connecting the two keeps your sales, payments, and labor costs visible in your general ledger. Sales orders and payments from each Toast location flow into Zoho Books as customer invoices and journal entries on your account structure, and labor shift totals post as payroll expenses. ml-connector bridges the very different OAuth2 flows on each side and handles Toast's multi-location setup and regional Zoho routing.

How Zoho Books works

Zoho Books is a cloud-based accounting platform for SMBs handling invoicing, bills, purchase orders, expenses, and multi-currency accounting. It exposes contacts, invoices, bills, purchase orders, payments, items, chart of accounts, journals, and expenses through a REST API authenticated with OAuth2 (user-delegated refresh token, not machine-to-machine). Access tokens valid for 1 hour. Every call requires an organization ID query parameter and routes to a region-specific base URL determined by the region field in the OAuth token response. Zoho Books supports outgoing webhooks for invoices, bills, purchase orders, contacts, payments, expenses, and sales orders, or polling via offset-based pagination with a has_more_page indicator. Rate limit is 100 requests per minute with daily limits varying by plan.

How Toast works

Toast is a cloud restaurant management platform exposing sales orders, checks, payments, menu items, employees, shifts, and time entries through OAuth2 Client Credentials (machine-to-machine). Every request requires two headers: a bearer token and a Toast-Restaurant-External-ID for location-specific access. Toast supports both webhooks and polling. Webhooks push order_updated, channel_order_updated, stock, and menu change events with HMAC-SHA256 signature verification, but do not cover payments or labor data. Polling is available via GET /ordersBulk with business date filtering and cursor-based pagination. Voided orders and checks are still returned and must be filtered. Write operations are limited to employees and specific order updates; menu items and configuration are read-only. Rate limit is 20 requests per second, with stricter limits on menu and historical data APIs. Multi-location requires a separate Toast-Restaurant-External-ID per location.

What moves between them

Sales orders, payments, and labor data move from Toast into Zoho Books. Each Toast location sends its daily orders via ordersBulk polling (with business date accounting for the location's configured closeout hour) into Zoho Books as customer invoices mapped to the Chart of Accounts. Toast payments post as customer payment entries in the corresponding organization. Labor shifts roll up into journal entries against payroll or expense accounts. Revenue centers and service charges from Toast map to Zoho accounts and cost dimensions. The flow is read-mostly on Toast (no financial writes back); Zoho Books data does not flow back to Toast.

How ml-connector handles it

ml-connector stores the Zoho OAuth refresh token encrypted and uses it to obtain new access tokens every 55 minutes before expiry. It resolves the regional API endpoint from the Zoho token response and routes all calls there. For Toast, it exchanges client credentials for a bearer token and caches it to avoid hitting the auth rate limit. For multi-location restaurants, it retrieves all accessible Toast locations via GET /partners/v1/restaurants and loops through each location ID, setting Toast-Restaurant-External-ID on every request. It polls Toast ordersBulk each business date and filters out voided orders before posting. Service charges flagged as gratuity are handled per Toast's gratuityServiceCharge field. Because Toast webhooks are not guaranteed delivery, ml-connector runs a nightly reconciliation poll to catch any missed orders. Toast business dates are calculated per location's closeoutHour (e.g., a 1 AM sale belongs to the prior calendar day if closeout is 3 AM). It maps Toast SalesCategory and RevenueCenter to Zoho Chart of Accounts, handles Toast rate limits (20 req/sec default) with exponential backoff, and tracks every record in the audit trail for replay.

A real-world example

A casual-dining restaurant group runs 12 Toast locations and uses Zoho Books for consolidated accounting across all stores. Before the integration, managers exported daily sales totals from Toast into a spreadsheet and re-entered them into Zoho Books each morning, reconciling payment processing reports by hand and logging labor totals separately. After payroll, the CFO had to manually post labor costs against the right expense accounts per location. With Toast and Zoho Books connected, each location's daily orders post as invoices, payments post as customer payments, and labor shifts roll up into journal entries tagged to the right cost center. Daily sales appear in the ledger automatically, multi-location reporting takes no manual effort, and reconciliation happens at the account level.

What you can do

Sync Toast sales orders from all locations into Zoho Books as customer invoices, automatically handling business date logic and location-specific closeout hours.
Post Toast payments and service charges into Zoho Books as customer payment entries and journal lines mapped to the Chart of Accounts.
Roll up Toast labor shifts into payroll or expense journal entries with cost center allocation per location.
Filter voided orders and checks before posting, and handle service charges classified as gratuity per Toast configuration.
Authenticate Toast with OAuth2 Client Credentials and Zoho Books with user-delegated OAuth2, route Zoho calls to the correct regional endpoint, and run nightly reconciliation polls since Toast webhooks are not guaranteed delivery.

Questions

How does ml-connector handle Toast's multi-location setup?: Toast requires a separate Toast-Restaurant-External-ID for each location. ml-connector retrieves all accessible locations via GET /partners/v1/restaurants, loops through each location ID, and sets the header on every request. Sales orders, payments, and labor data are retrieved per location and tagged with the location in Zoho Books for multi-location reporting.
What happens with voided orders and service charges flagged as gratuity?: Voided orders and checks are returned by Toast's API but must be filtered before posting to Zoho Books. ml-connector filters voided==true before creating invoices. Service charges may be classified as gratuity (gratuityServiceCharge:true), affecting tip and revenue recognition. ml-connector respects this flag and posts them correctly.
Why does ml-connector poll Toast nightly if webhooks are available?: Toast webhooks are not guaranteed delivery and do not cover payments or labor data. ml-connector uses webhooks where available for real-time notification but runs a nightly reconciliation poll via ordersBulk as a safety net to catch missed orders and ensure all payments and shifts are posted to Zoho Books.

Connect Zoho Books and Toast

Free to use. Add your credentials, ping your real systems, and see if we fit.

Get started