Xero and Toast integration

What moves between them

The main flow is Toast into Xero. ml-connector reads Toast sales orders and payments using the businessDate parameter, aligned to each restaurant's closing time. Order line items are mapped to Xero sales invoice lines, with service charges and tips mapped to separate Xero accounts or line items. Payments are posted as Xero payments against the invoices. Reconciliation runs nightly per business date to catch any orders that may have been missed by the webhook stream. Multi-location restaurants are handled by routing each Toast location to its corresponding Xero organization via the Xero-tenant-id and Toast-Restaurant-External-ID headers.

How ml-connector handles it

ml-connector stores OAuth2 credentials for both Xero and Toast, refreshing Toast bearer tokens before they expire and caching them to avoid rate-limit penalties on repeated authentication. For Xero, it manages the 30-minute access token and 60-day refresh token lifecycle. Every Toast order read is checked for the voided flag and skipped if set, and service charges classified as gratuity are handled per your configuration. Business dates are computed per restaurant, accounting for that location's closeoutHour, so orders are posted to the correct Xero period. Fundraising items in selections are excluded from net sales. Xero's 5-concurrent-request and 60-per-minute rate limits are respected via request queuing and backoff. Toast's token requirement per request is handled transparently at the platform layer. Because Toast webhooks are not guaranteed delivery, ml-connector runs a nightly reconciliation poll using the /ordersBulk endpoint with each business date to ensure no sales slip through. Every order and payment carries a full audit trail and can be replayed if a downstream Xero call fails.

A real-world example

A restaurant group with three locations uses Toast for POS and payments at each location and a single Xero general ledger for consolidated accounting. Before the integration, the office manager exported orders and payments from Toast each night and manually created invoices and payment entries in Xero the next morning, a two-hour process per day. With Toast and Xero connected, each night's sales and payments from all three locations flow into Xero automatically, mapped to the correct revenue centers and accounts. Month-end closes start with current sales numbers, eliminating the manual re-entry step and the reconciliation mismatches that came with it.

What you can do

• •Post Toast sales orders into Xero as invoices, mapped to the correct revenue centers and accounts.
• •Sync payments from Toast into Xero's payment records with full audit trail.
• •Handle multi-location Toast restaurants by routing each location to its corresponding Xero organization.
• •Manage business date reconciliation accounting for each Toast location's configurable close time.
• •Filter voided orders and categorize service charges and gratuity per your accounting rules.

Questions

How does ml-connector handle multiple Toast locations in one Xero organization?

Each Toast location has its own Toast-Restaurant-External-ID. ml-connector reads orders for each accessible location and routes them to the correct Xero organization via the Xero-tenant-id header. If all locations share one Xero org, orders are consolidated by location; if each location has its own Xero org, they are routed separately.

What does ml-connector do about voided orders and service charges?

Voided orders are returned by the Toast API but flagged with voided=true. ml-connector filters them before posting to Xero so the general ledger does not record reversed transactions. Service charges are mapped to your configured Xero accounts; if classified as gratuity, they can be routed to a separate tip account.

Why does business date matter, and how does ml-connector handle it?

Each Toast restaurant has a closeoutHour that defines when the business day ends. A sale at 1 AM on June 12 belongs to June 11 if closeoutHour is 3 AM. ml-connector computes business dates per location and reconciles orders nightly, posting them to the correct Xero period so your daily and monthly close remain accurate.