How a restaurant brand on Toast can turn orders, locations and menus into guest records, visit and spend profiles, and catering leads HubSpot can segment, automate and report on, and which Toast API access tier each part needs.
Toast is a restaurant point-of-sale and operations platform. Every order, check, menu and location lives in Toast, and multi-location brands manage them as one restaurant group.
Public documentation, but production access needs vendor approval, certification, a paid license or a specific plan.
Open with conditions. Standard API access is read-only and needs the right Toast subscription at each location. Anything that writes to Toast needs a custom integration approved through Toast.
Based on the vendor's public documentation. Access terms are confirmed with the vendor and the client in discovery.
Toast can feed HubSpot reliable order, spend and location data, with guest identity strongest on takeout and delivery orders.
Campaign Creators assessment
Toast publishes REST APIs for orders, menus, restaurants, configuration, labor and stock, authenticated with client credentials. A restaurant brand can buy Standard API access and create its own read-only credentials, including webhooks for orders and menus. That is enough for a HubSpot integration that reads data. Writing to Toast needs a custom integration arranged through the brand's Toast account representative. The main limit is identity: Toast documents that standard API access returns guest details only for takeout and delivery orders, so dine-in spend is reported by location unless the guest is otherwise identified.
Scores are CC judgments from Toast's public developer documentation. The brand's access tier, scopes and Toast subscription are confirmed per location in discovery.
With Standard API access, the brand creates read-only credentials in Toast Web and subscribes a CC-hosted URL to the orders webhook, which fires on every new or updated order.
Guest name, email and phone come back only for takeout and delivery orders. Dine-in spend without a guest attached is reported at the location level, not on a contact.
Standard API access is read-only and needs the right Toast subscription at each location. Anything that writes to Toast needs a custom integration approved through Toast.
Seven building blocks shape the integration. Three carry it, two enrich it, one sits outside the published read APIs, and one is a scope decision.
Orders, checks, selections and payments for each location, searchable by business date for backfill.
Pushes the full order to a CC-hosted URL whenever an order is created or updated.
Location name, address and hours, plus the dining options and revenue centers that give each order its meaning.
Fully resolved menus per location, used to group order selections into categories for item affinities.
Employees, shifts, inventory and cash drawer events. Useful for operations, rarely for guest marketing.
Toast's loyalty and gift card APIs are built for outside providers to plug into Toast. Reading the brand's own Toast loyalty members and gift card balances is not part of standard API access.
HubSpot becomes the one place guest marketing runs from. If guest messages go out from Toast today, the plan assigns each message type to one sender.
Toast pushes order events to a CC-hosted endpoint. The integration layer fetches guest details by order GUID, resolves identity, rolls up visits and spend, and writes to HubSpot in batches. Locations and menus sync daily.
A busy location closes thousands of checks a week. HubSpot stores identified orders and rollups; line-level detail stays in Toast and its reporting.
Every order carries its restaurant GUID, so spend is reported by location even when the guest is anonymous.
The default build reads from Toast. Any write to Toast is a named item in the SOW with its own Toast approval.
Each phase ends on a gate the brand signs off before the next begins, so the fixed scope holds even if Toast access or data differs from what was expected.
Confirm the brand has Standard API access and the Toast subscription each location needs for webhooks. Create read-only credentials in Toast Web with the agreed scopes, and decide whether any write needs a custom integration request.
Pull 30 days of orders. Measure the share of orders with a guest, how dining options and revenue centers are set up, and how catering orders are marked.
List guest messages sent today, by Toast or anyone else, and assign each one to a single sender. Map opt-outs to HubSpot subscription types.
Create the Location object, guest rollup properties, the order pipeline, the catering deal pipeline and affinity options in a HubSpot sandbox.
Build the webhook receiver, order enricher, identity resolver, aggregator and batch writer, paced to Toast's per-location limits.
Load 12 months of orders through ordersBulk in windows of one month or less, then compute rollups once.
Build win-back, first-visit and catering workflows with sends paused, run two weeks in parallel, then add remaining locations in waves.
Toast field names follow the Orders, Restaurants and Menus APIs as Toast documents them. Exact paths and catering markers are confirmed against the brand's locations during discovery.
| Toast field | HubSpot property | Object | Direction | Notes |
|---|---|---|---|---|
| Guest identity · check customer (guest.pi:read) | ||||
| checks[].customer.email | Contact | Toast → HS | Match key #1. Takeout and delivery orders. | |
| checks[].customer.phone | phone | Contact | Toast → HS | Match key #2. Normalize to E.164. |
| checks[].customer.firstName / lastName | firstname, lastname | Contact | Toast → HS | Fill blanks only. |
| checks[].customer.guid | toast_guest_id | Contact | Toast → HS | Stored for matching later orders. |
| first order businessDate | toast_first_order_date | Contact | Toast → HS | |
| deliveryInfo.city / zipCode | city, zip | Contact | Toast → HS | Needs delivery address scope; off by default. |
| Visits & spend · Orders API | ||||
| max(order.businessDate) | toast_last_order_date | Contact | Toast → HS | Identified orders only. |
| count(orders) 90 days / 12 months | toast_orders_90d, toast_orders_12m | Contact | Toast → HS | Computed in the integration layer. |
| sum(checks[].amount) | toast_lifetime_spend | Contact | Toast → HS | Before tax and tip; rule agreed in discovery. |
| avg(checks[].amount) | toast_avg_check | Contact | Toast → HS | |
| recency, frequency, spend | toast_rfm_segment | Contact | Toast → HS | Segment labels agreed with marketing. |
| restaurant GUID (mode) | toast_favorite_location | Contact | Toast → HS | Most-ordered location in 12 months. |
| diningOption behavior | toast_preferred_channel | Contact | Toast → HS | Takeout, delivery or dine-in. |
| order.source | toast_order_source | Order | Toast → HS | Online ordering, in store and other channels. |
| selections[] by menu group | toast_item_affinities | Contact | Toast → HS | Top menu groups, not every item. |
| Orders, catering & groups | ||||
| order.guid | hs_external_order_id | Order | Toast → HS | Identified orders only. |
| order.businessDate / closedDate | hs_createdate, toast_business_date | Order | Toast → HS | |
| checks[].totalAmount | hs_total_price | Order | Toast → HS | |
| order.numberOfGuests | toast_guest_count | Order | Toast → HS | |
| catering dining option or total over threshold | Deal in Catering pipeline | Deal | Toast → HS | Marker and threshold agreed with the brand. |
| checks[].appliedLoyaltyInfo | toast_loyalty_identifier | Contact | Toast → HS | Present when a loyalty service is attached. |
| Locations & menus · Restaurants, Config, Menus | ||||
| restaurant GUID | toast_restaurant_guid | Location (custom) | Toast → HS | Primary key. |
| restaurant name / location address | name, address fields | Location (custom) | Toast → HS | |
| restaurant group GUID | toast_group_guid | Location (custom) | Toast → HS | Groups locations for multi-brand reporting. |
| dining options | toast_dining_options | Location (custom) | Toast → HS | Reference for channel mapping. |
| menu groups | affinity options | Contact | Toast → HS | Daily; one call per second per location. |
Toast uses client credentials and a per-request location header; HubSpot uses one app token. Values Toast does not publish are marked for confirmation.
| Topic | Toast | HubSpot |
|---|---|---|
| Authentication | POST /authentication/v1/authentication/login with clientId, clientSecret and userAccessType TOAST_MACHINE_CLIENT. Returns a Bearer JWT with an expiry in seconds. | Private app access token or OAuth 2.0 public app. |
| Location targeting | Every location-specific call carries the Toast-Restaurant-External-ID header with the restaurant GUID. | One portal for all locations; Location records separate them. |
| Access tiers | Standard API access: read-only GET, credentials created by the brand in Toast Web. Custom integration: read and write, arranged through the Toast account representative. Partner integration: issued by the Toast integrations team. | Self-serve in the portal; custom objects need an Enterprise hub. |
| Real-time | Webhooks for orders, menus, stock, restaurant availability, online ordering schedule and packaging. Standard API access needs the Manage Integrations permission and the required Toast subscription at each location. | Webhooks or workflows for HubSpot-side changes, such as unsubscribes. |
| Rate limits | 20 requests per second and 10,000 per 15 minutes. GET /menus: 1 per second per location. ordersBulk: 5 per second per location, windows of one month or less. 429 with Retry-After. | Per-10-second burst and daily limits by subscription tier. |
| Guest data | guest.pi:read returns the check customer on takeout and delivery orders only. The orders webhook omits guest details. | Contacts hold only what the brand approves; no card data. |
| Sensitive data | Payments carry card references. CC never syncs card numbers, only tender type and amount. | No payment card data stored in the CRM. |
Severity reflects impact on the SOW, not technical difficulty alone.
Spend without a guest cannot reach a contact. Measure the identified share in the data audit and set reporting expectations before promising guest-level automation.
Standard API access is read-only. Writing guests, orders or menus to Toast needs a custom integration approved through Toast. Make the tier a client-owned dependency in the SOW.
Toast's own loyalty members and gift card balances are not in the published read APIs. Confirm with the Toast account representative before scoping them.
If Toast already sends guest marketing, agree which system sends each message type, so guests hear from the brand once.
Writing every check to HubSpot would exhaust limits and clutter the CRM. Aggregate in the integration layer and pace backfills to Toast's per-location limits.
Webhooks need the right Toast subscription at each location. A location without it is covered by a scheduled ordersBulk pull until it is upgraded.
Last order, frequency, lifetime spend, average check, favorite location and channel become filters for every list and workflow.
Recency, frequency and spend segments recalculate after each order, so win-back and VIP journeys always target the right guests.
Catering and large-party orders create deals for the catering or events team, with follow-up tasks and repeat-order nurture.
Guests who order from a menu group get launches and offers for that group, by location.
Location records tie guests, orders and campaigns together, so marketing can report campaign-driven orders by site and by brand.
A guest's first online or delivery order starts a welcome journey tailored to how they ordered.
The integration grows with the brand's Toast access. Read-only access delivers most of the marketing value; write access is added only when a use case needs it.
All custom properties use the toast_ prefix in a Toast property group. Rollups are calculated in the integration layer so they are consistent across reports.
| Internal name | Label | Object | Type | Source / logic |
|---|---|---|---|---|
| toast_guest_id | Toast Guest ID | Contact | Single-line text | checks[].customer.guid |
| toast_first_order_date | First Order | Contact | Date | Earliest identified order |
| toast_last_order_date | Last Order | Contact | Date | Latest identified order |
| toast_orders_90d | Orders (90 days) | Contact | Number | Count of identified orders |
| toast_orders_12m | Orders (12 months) | Contact | Number | Count of identified orders |
| toast_lifetime_spend | Lifetime Spend | Contact | Number (currency) | Sum of check amounts |
| toast_avg_check | Average Check | Contact | Number (currency) | Lifetime spend ÷ orders |
| toast_rfm_segment | RFM Segment | Contact | Dropdown | Recency, frequency and spend bands |
| toast_favorite_location | Favorite Location | Contact | Dropdown (location list) | Most-ordered location, 12 months |
| toast_preferred_channel | Preferred Channel | Contact | Dropdown | Dining option behavior |
| toast_item_affinities | Item Affinities | Contact | Multiple checkboxes | Top menu groups |
| toast_restaurant_guid | Toast Restaurant GUID | Location | Single-line text | Unique key |
Choose the APIs and fields for this engagement and the direction each one syncs. Required fields are the keys the integration cannot run without. Copy the summary into the SOW or a reply to the client.
Based on public documentation from Toast. Access tier, scopes and webhook availability are confirmed for each of the brand's locations during discovery.
Yes, through a custom build on Toast's REST APIs. Standard API access gives the brand read-only credentials, including orders and menus webhooks, which is enough for an integration that reads Toast data. Writing to Toast needs a custom integration approved through Toast.
Guests on takeout and delivery orders become HubSpot contacts with visit, spend, favorite location and item affinity rollups. Identified orders sync to HubSpot orders, each Toast restaurant becomes a Location record, and catering orders become deals. Dine-in spend without a guest attached is reported by location.
Toast owns orders, checks, menus and locations, and HubSpot stores identified orders and rollups rather than every line item. HubSpot owns guest marketing, with each guest message type assigned to one sender. The default build only reads from Toast.
Seven phases, each closed by a brand sign-off: discovery and access, a data audit with identity rules, messaging ownership, the HubSpot data model, the integration build on a pilot location, a 12-month order backfill, and a two-week parallel run before workflows go live and remaining locations are added in waves.
Timeline and cost depend on the number of locations, the Toast access tier, the order history in scope and whether any write to Toast is needed. Campaign Creators confirms these in discovery and provides a fixed scope before the build starts.