Sage X3 and Toast integration

What moves between them

The flow runs from Toast into Sage X3. Daily sales orders, checks, and payments from Toast are read via a combination of webhooks for real-time events and nightly reconciliation polls for each restaurant's business date, since Toast webhooks are not guaranteed. Itemized revenue by sales category and payment method is posted into X3's GL accounts and sales dimension accounts on the business date the transaction occurred. Menu items and service charges are mapped to X3 product and revenue GL dimensions so revenue lands on the correct accounts. Voided orders and fundraising items are filtered out before posting. The flow is one-way into X3; no write-back to Toast occurs.

How ml-connector handles it

ml-connector stores OAuth2 credentials for both sides encrypted and caches Toast bearer tokens to avoid re-authentication on every request, which would hit Toast's auth rate limit. It manages X3's 5-minute access token refresh by re-authenticating and storing the new token before the old one expires. For multi-location Toast deployments, it stores the restaurant GUID for each location and uses the correct Toast-Restaurant-External-ID header on every call. It polls Toast at the end of each business day using Toast's business date parameter, accounting for that location's configured close-out hour so transactions are dated correctly. Webhooks from Toast are processed in real-time when enabled, with HMAC-SHA256 signature verification, but nightly polling serves as a safety net since Toast webhooks are not guaranteed delivery. Voided orders, voided checks, and fundraising items flagged in selections are filtered out before posting revenue to X3. GL postings are batched by date and GL account to minimize journal entry line count. Every transaction carries a full audit trail with the original Toast order ID and receipt number so disputes can be traced back to the POS.

A real-world example

A fast-casual restaurant group runs Sage X3 for multi-location accounting and inventory control, and Toast for POS and order management across 12 locations. Before the integration, each location manager exported daily sales and payment reconciliation from Toast and sent it to the back office, where an accountant manually created GL journal entries to record the day's revenue and payments in X3. On busy days, reconciliation was delayed, and month-end close required 2-3 days of chasing exceptions between systems. With Toast and X3 connected, revenue and payment records from each POS post into X3 each morning, allocated to the correct GL accounts and sales categories by menu item. Cash reconciliation is instant, and the back office can close the books immediately after the last location's reconciliation pull.

What you can do

• •Read Toast sales orders, checks, and payments via webhook and nightly reconciliation poll, posting itemized revenue and payment records into Sage X3 GL on the correct business date.
• •Map Toast menu items, sales categories, and service charges to Sage X3 GL revenue accounts and product dimensions so every transaction lands on the correct account.
• •Handle multi-location Toast deployments by storing and using the correct restaurant ID per location on every API call.
• •Filter voided orders, voided checks, and fundraising items flagged in selections before posting revenue to X3, preventing reversals from appearing as duplicate entries.
• •Manage OAuth2 authentication on both sides, including X3's 5-minute token expiry and Toast's auth rate limit with token caching and nightly business-date accounting for Toast close-out hour.

Questions

How does the integration handle Toast's multi-location architecture?

ml-connector stores the Toast restaurant GUID for each location and includes the correct Toast-Restaurant-External-ID header on every API call. It reconciles each location's transactions independently at the end of that location's business day, accounting for that restaurant's configured close-out hour so transactions are dated correctly in X3. A single configured flow can sync all locations by iterating through the restaurant list on each poll cycle.

Which Toast transactions post to Sage X3 GL, and which are filtered out?

Sales orders, checks, and payments from Toast all post revenue and payment records into X3. Voided orders, voided checks, and transactions flagged as voided are filtered out. Fundraising items flagged in menu selections are excluded from net revenue. Service charges classified as gratuity are excluded from taxable sales. Discounts and payment method breakdowns are posted to their mapped GL accounts.

How does ml-connector reconcile Toast's webhook delivery limitations with accounting accuracy?

Toast webhooks push order and stock events in real-time when enabled, but Toast does not guarantee webhook delivery. ml-connector implements nightly reconciliation polling at the end of each business date as a safety net, using Toast's businessDate filter to retrieve all transactions for that day. If a webhook was missed during the day, the nightly poll will catch and post the transaction. Every transaction carries its Toast order ID and receipt number for full traceability back to the POS.