Microsoft Dynamics NAV and Toast integration

What moves between them

Toast sales orders, checks, and payments flow daily into Microsoft Dynamics NAV general ledger as sales journal entries. The integration polls Toast each business date after the restaurant's configured closeout hour and reconciles orders, checks, and payments by totaling net sales and tender amounts. Voided transactions are excluded. Daily totals are posted into NAV as sales invoice records or journal entries against the sales account and cost center configured per Toast location. Customer records and menu items are read from Toast but not updated in NAV, and general ledger entries posted to NAV are immutable. The integration never writes back to Toast.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Toast side it caches the OAuth bearer token and refreshes it proactively before expiry to avoid auth rate limits, accepts the restaurant GUID per location, polls Toast after the configured closeout hour each business date (respecting the fact that a 1 AM sale belongs to the prior business date if closeout is at 3 AM), filters voided orders and checks before totaling, and maps Toast revenue categories and tenders to NAV sales accounts and cost centers. On the NAV side it accepts the tenant ID and company ID for online instances or the server URL for on-premises deployments, uses OAuth client credentials or basic auth depending on the deployment type, and posts daily totals as sales journal entries or sales invoices. If a restaurant is multi-location, each location has its own Toast-Restaurant-External-ID and its own daily job. Toast does not document an Idempotency-Key header, so ml-connector uses the externalId field on orders for deduplication and checks if a record was already created before retrying. Every record carries a full audit trail.

A real-world example

A regional restaurant group with 12 locations runs Toast for point-of-sale and kitchen management and Microsoft Dynamics NAV for general ledger and financial reporting. Before the integration, the accounting team polled Toast each morning, exported daily sales and tender summaries for each location, and re-entered the totals into NAV sales invoices and journals by hand. Reconciling Toast against NAV took 2 hours daily and was prone to entry errors. With Toast and NAV connected, each location's daily sales flow into NAV automatically after closeout, allocated to the right revenue account and cost center, and the reconciliation is complete by the time the accounting team arrives. Month-end close starts with sales and tenders already posted and verified.

What you can do

• •Poll Toast daily after each restaurant's configured closeout hour and post sales orders, checks, and payments into NAV general ledger.
• •Map Toast revenue categories, tenders, and service charges to NAV sales accounts, cost centers, and general ledger dimensions.
• •Handle multi-location Toast accounts by polling and posting each location separately with its own credentials.
• •Authenticate Toast with OAuth 2.0 client credentials and Microsoft Entra ID, managing token expiry and caching to avoid rate limits.
• •Exclude voided transactions, filter fundraising items, and reconcile Toast daily totals against NAV invoice and journal records with full audit trail.

Questions

How does the integration handle Toast's business date logic and multi-location setup?

Toast's business date (YYYYMMDD) is determined by each restaurant's configurable closeoutHour. If a sale occurs at 1 AM June 12 but the closeout hour is 3 AM, the sale belongs to June 11 business date. ml-connector polls each location separately using its own Toast-Restaurant-External-ID header and OAuth token, respecting the configured closeout hour, so each location's daily sales post to NAV on the correct date.

What happens to voided orders, checks, and payments in Toast?

Toast returns voided transactions in API responses but flags them with voided=true. ml-connector filters out any transaction with voided=true before summing daily totals and posting to NAV, so voided sales do not appear in the general ledger. Service charges classified as gratuity are also excluded from net sales calculations.

Why does ml-connector cache Toast's OAuth bearer token?

Toast enforces a 20 request-per-second rate limit globally and an auth rate limit that is hit quickly if every request re-authenticates. ml-connector caches the token after the initial OAuth login and refreshes it proactively before expiry. If a request returns 401, the token is refreshed and the request is retried, avoiding rate-limit lockouts during nightly reconciliation polls.