HubSpot + Toast integration

Restaurant groups do not usually want a CRM for their diners. They want one for everything around the dining room: catering enquiries, private events, franchise development, supplier relationships and the marketing list that fills a quiet Tuesday. The trouble is that all the evidence of what is working sits in the point of sale, and the point of sale is not somewhere a marketing manager goes.

The clearest example is catering and private events. An enquiry arrives through a form, a sales person quotes it, and the event happens. Whether it actually happened, what it was worth and whether the guest came back are facts the restaurant system holds and the pipeline does not, so the close rate everyone reports is an estimate. Connecting the two turns a quoted event into a confirmed one without anybody retyping a number.

Multi location groups add a second problem. Each restaurant is its own scope in Toast, which is sensible for an operating system and unhelpful for a head office that wants to compare sites, roll up performance or run a campaign across a region. Toast is also unusual among the systems on this site in that the constraint is commercial before it is technical. The documentation is good and the endpoints are capable, and you still cannot start until Toast has issued credentials, which is a conversation with a timeline of its own.

Five object types carry most of the value. Restaurants become companies, guests become contacts, orders and payments become custom objects, and menu items become products.

One company per location is the right shape, because it matches how the API behaves. Every request is scoped to a restaurant, so the integration is already carrying a location identifier on every record, and modelling locations as companies keeps ownership, reporting and rate limiting aligned with reality. A management group sits above them as a parent company.

Guest coverage is partial and should be described that way to the business before the first load. A walk in who pays cash produces an order with no guest attached, so contact records exist for the subset of trade that identifies itself. Orders belong on a custom object rather than a deal, because a restaurant order is a completed transaction rather than an opportunity moving through stages, and thousands of them in a pipeline make the pipeline useless.

Everything flows one way. Standard API access is read only by design, and nothing in a CRM should be writing to a live restaurant system.

The pattern is polling with a watermark, one restaurant at a time. A scheduled job asks the bulk orders endpoint for orders whose modified date falls in a window, pages through the results, and writes into HubSpot with batch upserts keyed on the Toast identifier, followed by a separate associations pass. API paths on the HubSpot side are pinned to version 2026-03.

Token handling is part of the architecture rather than a detail. Toast asks integrations to request one or two tokens a day, never more than twice in an hour, and to reuse a token for at least half an hour, with terminated access as the stated consequence for ignoring that. So the token cache is shared across every location the job touches, not created per run.

Admission control is per location. The documented budget is 20 requests per second and 10,000 per 15 minutes against a restaurant, with tighter limits on menus and bulk orders, so the scheduler paces each location separately and records where each one stopped.

There is no app, so the real choice is between a service and an automation platform, and the deciding factor is how many restaurants there are. One site that wants new guests in a list can be done with automation, and it will not survive contact with order history. Several locations means several scopes, several rate budgets and several watermarks, and that state has to live somewhere a service can hold it. The other decision, made before either, is which Toast access model you are on: read only standard access is enough to feed a CRM, and a partner account is what you need if anything ever has to be written back.

Token handling and per location rate budgets are specific to Toast, and they cause most of the trouble on a restaurant build.

1. Scope. We start the access conversation with Toast on day one, because it is the longest lead item, and we confirm which account model the group qualifies for before scoping anything technical.
2. Architect. We fix the location model first, then the order object, then decide what guest coverage the business can reasonably expect.
3. Build. A shared token cache, batch upserts keyed on Toast identifiers, a separate associations pass, and per location watermarks from the first run.
4. Validate. The sandbox Toast provides on one side, a HubSpot sandbox portal behind a fail closed allowlist on the other, then a cutover by credential swap.
5. Operate. Runs report per location counts and the guest attachment ratio, and the connection list is checked before each cycle so a disconnected restaurant stops cleanly.