Toast × HubSpot
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.
Does Toast integrate with HubSpot?
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.
Push-based orders, self-serve credentials
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.
Anonymous dine-in checks
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.
Access tier sets what is possible
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.
Which Toast APIs does the integration use?
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 API
orders:read · GET /orders/v2/ordersBulkOrders, checks, selections and payments for each location, searchable by business date for backfill.
- Dining option, revenue center, source and guest count
- Check totals and menu item selections
- guest.pi:read adds the guest on takeout and delivery
Orders webhook
Event type order_updatedPushes the full order to a CC-hosted URL whenever an order is created or updated.
- Guest details omitted from the push; fetched by order GUID
- Payloads can exceed 600 KB
- Subscribed in Toast Web under API access
Restaurants & configuration
restaurants:read · config:readLocation name, address and hours, plus the dining options and revenue centers that give each order its meaning.
- One HubSpot Location record per Toast restaurant
- Dining option behavior: dine-in, takeout, delivery
- Low change rate; synced daily
Menus API
menus:read · Menus v2Fully resolved menus per location, used to group order selections into categories for item affinities.
- Menu groups become affinity options
- Menus webhook for changes
- One request per second per location
Labor, stock & cash
labor:read · stock:read · cashmgmt:readEmployees, shifts, inventory and cash drawer events. Useful for operations, rarely for guest marketing.
- Server name on a check, if wanted
- Out-of-stock items to pause promotions
- Usually left out of scope
Toast loyalty and gift cards
Not in the published read APIsToast'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.
- Loyalty info on a check appears when a loyalty service is attached
- Confirm any other access with the Toast account representative
- Gift card sales may appear as order items; confirm in discovery
Guest messaging in HubSpot
Email · SMS · offersHubSpot 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.
- List which guest messages run today, and from where
- Move each one to HubSpot or leave it in Toast, never both
- Bring existing opt-outs into HubSpot first
How does the Toast HubSpot integration work?
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.
Aggregate, don't mirror
A busy location closes thousands of checks a week. HubSpot stores identified orders and rollups; line-level detail stays in Toast and its reporting.
Location is always known
Every order carries its restaurant GUID, so spend is reported by location even when the guest is anonymous.
Read first, write by exception
The default build reads from Toast. Any write to Toast is a named item in the SOW with its own Toast approval.
What does Toast HubSpot integration setup involve?
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.
Discovery & access
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.
Data audit & identity rules
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.
Messaging ownership
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.
HubSpot data model
Create the Location object, guest rollup properties, the order pipeline, the catering deal pipeline and affinity options in a HubSpot sandbox.
Integration build
Build the webhook receiver, order enricher, identity resolver, aggregator and batch writer, paced to Toast's per-location limits.
Backfill
Load 12 months of orders through ordersBulk in windows of one month or less, then compute rollups once.
Workflows, parallel run & rollout
Build win-back, first-visit and catering workflows with sends paused, run two weeks in parallel, then add remaining locations in waves.
What does the Toast HubSpot integration sync?
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. |
How are authentication and API limits handled?
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. |
What should you plan for, and what does the integration unlock?
Severity reflects impact on the SOW, not technical difficulty alone.
Challenges to plan for
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.
Opportunities in HubSpot
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.
Start with what Toast already gives you.
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.
- Locations first: one HubSpot Location record per Toast restaurant, grouped by brand.
- Orders next: identified takeout and delivery orders with visit and spend rollups and RFM segments.
- Catering and groups: large and catering orders become deals in their own pipeline.
- Extend by exception: write-back, loyalty or gift card data once Toast confirms the access.
Which HubSpot properties does the integration create?
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 |
Interactive scope builder
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.
Scope summary
Sources & verification
Based on public documentation from Toast. Access tier, scopes and webhook availability are confirmed for each of the brand's locations during discovery.
- Toast developer guide: Integration types
- Toast developer guide: Standard API access overview
- Toast developer guide: Standard API access scopes
- Toast developer guide: Standard API access webhook subscriptions
- Toast developer guide: Standard API access FAQs
- Toast developer guide: Orders webhook
- Toast developer guide: Rate limiting
- Toast developer guide: Authentication and restaurant access
Toast HubSpot integration FAQ
Does Toast integrate with HubSpot?
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.
What data syncs between Toast and HubSpot?
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.
Which system owns which data?
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.
What does setting up the Toast HubSpot integration involve?
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.
How long does the integration take and what does it cost?
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.
Ready to Get More From HubSpot?
Whether you’re implementing HubSpot, optimizing what you already have, connecting systems, or scaling your customer experience, we’ll help you figure out the right next step.
.png?width=1920&height=553&name=cc-logo-color%20(2024).png)