QuickBooks Online and Toast integration

What moves between them

Sales orders and payments flow from Toast into QuickBooks Online. Each Toast order maps to a QB Online Invoice, with line items matching Toast menu items and sales categories, and each Toast payment maps to a QB Online Payment. The flow runs on two cadences: webhooks provide near-real-time notification of order and menu changes, but ml-connector also polls for reconciliation at the end of each business date per location, using the correct closeoutHour to identify which sales belong to which date. Voided transactions are filtered out before posting. Reference data such as GL accounts and departments are aligned once during setup, so every order line lands on a valid account.

How ml-connector handles it

ml-connector stores both credential sets encrypted and uses OAuth 2.0 Client Credentials to authenticate with Toast, caching the access token to avoid hitting the auth rate limit on every request. For QuickBooks Online, it holds the realm_id from the OAuth callback and exchanges refresh tokens as needed to maintain a valid access token. On the Toast side, it iterates through all accessible restaurant locations via GET /partners/v1/restaurants and respects each location's Toast-Restaurant-External-ID and configurable closeoutHour when determining the business date. Orders arrive via webhook or are pulled via the ordersBulk endpoint with businessDate=YYYYMMDD, and voided orders are filtered out before mapping to QB Online Invoices. For deduplication, ml-connector uses the Toast externalId field to check if an order was already created before retrying. On the QuickBooks Online side, each Invoice includes a SyncToken for concurrency control and carries a custom field or memo linking back to the Toast order ID for audit. Payments follow the same pattern, mapping Toast payment methods to QB Online Payment accounts. ml-connector handles both the different auth flows and the different data shapes on each side, and because both systems support webhooks, it can react quickly to changes while also running a nightly reconciliation poll to catch any events that did not arrive via webhook.

A real-world example

A small casual restaurant group with three locations uses Toast for POS, labor, and inventory, and QuickBooks Online for bookkeeping and tax reporting. Before the integration, the manager exported Toast sales reports daily and re-entered the totals into QB Online by hand, then spent hours each month reconciling sales figures that were out of sync. The team also struggled with voided transactions and split checks that did not map cleanly from Toast to QB Online's Invoice structure. With Toast and QB Online connected, each day's orders post automatically as Invoices allocated to the correct GL revenue accounts, voided orders are filtered out, and payments reconcile cleanly. Month-end close is faster, and the sales-to-GL reconciliation is automatic.

What you can do

• •Post Toast orders as QuickBooks Online Invoices, with line items mapped to GL revenue accounts and departments.
• •Sync Toast payments to QB Online Payment records, matched to the correct GL accounts.
• •Handle multi-location restaurants by iterating through all accessible Toast locations and their configurable business-date closeout hours.
• •Filter voided orders, checks, and payments before posting to GL so only net sales are recorded.
• •Authenticate with OAuth 2.0 on both sides, cache Toast access tokens to avoid rate limits, and keep refresh tokens fresh.

Questions

How does ml-connector handle Toast's multi-location business dates and closeout hours?

Each restaurant location has its own Toast-Restaurant-External-ID and configurable closeoutHour. ml-connector retrieves all accessible locations, polls orders for each location with businessDate=YYYYMMDD, and interprets the business date according to that location's closeout time. A sale at 1 AM belongs to the prior business date if closeout is at 3 AM.

What happens to voided orders, checks, and payments?

Toast returns voided transactions with a voided flag. ml-connector filters these out before mapping to QB Online Invoices and Payments, so only net sales and collected payments post to GL. This prevents duplicate or negative revenue entries.

Does ml-connector rely on Toast webhooks only, or does it also poll?

ml-connector listens to Toast webhooks for near-real-time notification of order and menu changes, but webhooks are not guaranteed delivery. It also runs a nightly reconciliation poll at the end of each business date via the ordersBulk endpoint to ensure no sales slip through the webhook gaps.