Skip to main content

Toast Integration Guide

Welcome to the Toast integration guide! This guide will help you assist customers with connecting their Toast POS system to Pivot for employee and sales data synchronization.

What is Toast?​

Toast is a cloud-based restaurant POS system with strong presence in the US market. When integrated with Pivot, it allows businesses to:

  • Sync employee data between their Toast POS and Pivot
  • Track sales automatically with regular updates
  • View historical sales data for reporting and analysis
  • Link POS employees to Pivot profiles for better workforce management
  • Import time clock data for accurate payroll processing

Integration Approach (Internal)​

Pivot's Toast integration follows a two-phase approach:

Current Status (Jan 2026): Phase 1 - Working with beta customers using Standard API Access

Phase 1: Standard API Access (Current)​

Current Approach

Phase 1 allows Pivot to integrate with Toast customers without being listed in the Toast Marketplace. The customer generates their own API credentials and shares them with Pivot.

How It Works​

Toast offers "Standard API Access" - a self-service feature where restaurant employees can generate API credentials directly from Toast Web. These credentials can be shared with third parties (like Pivot) to access the restaurant's data.

Capabilities & Limitations​

FeatureAvailable
Read employee data✅ Yes
Read time clock entries✅ Yes
Read sales/orders✅ Yes
Read tips✅ Yes
Write data to Toast❌ No (read-only)
Sandbox environment❌ No (production data only)

Read-only is sufficient for Pivot's needs - we pull data FROM Toast, we don't push data TO Toast.

What the Customer Needs to Do​

The customer must generate API credentials from their Toast account and share them with Pivot.

Prerequisites​

  • Active Toast account with Restaurant Management Suite (RMS) Essentials or higher
  • Manage Integrations permission in Toast
  • Must be an active employee of the Toast location

Step-by-Step Instructions for Customer​

  1. Log into Toast Web at https://www.toasttab.com/login

  2. Navigate to API Access

    • Go to Integrations → Toast API Access → Manage credentials

  3. Create New Credentials

    • Click Create credentials (or similar)
    • Select the location(s) to grant access to
    • Select the required scopes (see below)

  4. Copy Credentials

    • Copy the Client ID
    • Copy the Client Secret (only shown once!)

  5. Share with Pivot

    • Securely send the Client ID and Client Secret to Pivot
    • Also provide the Restaurant GUID (found in Toast account settings)

Required Scopes​

When creating credentials, the customer should enable these scopes:

ScopePurpose
labor.employees:readSync employee roster
labor.timeEntries:readImport time clock data
orders.readSync sales and order data
config.readRead restaurant configuration

What Pivot Receives from Customer​

ItemDescriptionExample
Client IDAPI authentication identifierabc123-def456-...
Client SecretAPI authentication secretsecret-xyz-...
Restaurant GUIDUnique restaurant identifier12345678-abcd-...

Storing Credentials in Pivot​

Credentials are stored in Firebase RTDB following the existing pattern:

{
  "ToastSettings": {
    "companyId123": {
      "clientId": "customer-generated-client-id",
      "clientSecret": "customer-generated-secret",
      "restaurantGuid": "restaurant-guid-from-toast",
      "credentialType": "standard_api_access",
      "isActive": true,
      "connectedAt": "2026-01-15T10:00:00Z",
      "lastSync": null
    }
  }
}

Phase 1 Limitations​

  • Manual onboarding - Each customer must generate and share credentials manually
  • No automatic connection - Unlike Partner Connect, there's no OAuth flow
  • Production data only - No sandbox; testing happens against real customer data
  • Credential rotation - If customer rotates credentials, they must share new ones manually

Phase 2: Partner Integration (Future)​

Future State

Phase 2 requires Toast Partner Program approval and Marketplace listing. This enables OAuth-based customer connections and removes the need for manual credential sharing.

Why Partner Integration​

Once Pivot has validated the integration with Phase 1 customers, we'll pursue full partner status for:

  • Seamless customer onboarding - Customers connect via Toast Marketplace with one click
  • OAuth flow - No manual credential sharing
  • Scalability - Can onboard many customers without manual steps
  • Visibility - Listed in Toast Marketplace for discovery

Partner Development Flow​

Partner Credentials (Future)​

CredentialDescriptionWhen
Sandbox clientIdTest environment identifierAfter partner approval
Sandbox clientSecretTest environment secretAfter partner approval
Production clientIdLive environment identifierAfter certification
Production clientSecretLive environment secretAfter certification

Current Partner Status​

  • ✅ Toast contact established
  • ✅ API documentation received
  • ⏳ Sandbox access not available at current partner tier
  • ⏳ Pursuing Phase 1 (Standard API Access) first to validate integration

Setting Up the Integration (Customer-Facing)​

How Customers Connect Toast to Pivot​

The integration is initiated through Toast's Partner Connect feature in Toast Web.

1. Log into Toast Web​

The customer needs to access their Toast account at Toast Web (not the POS terminal).

2. Navigate to Integrations​

Go to Integrations → Integration management → Browse & purchase integrations.

3. Find Pivot​

Search for "Pivot" in the available integrations list.

4. Click Add Now​

Click the "Add Now" button on the Pivot integration card.

5. Select Locations​

Using the Select Locations dropdown, check off the location(s) to connect and click Apply.

6. Confirm​

Review the selected locations and click Confirm to complete the setup.

Note: The customer must have the Account Admin > Manage Integrations permission in Toast to enable integrations.

7. Automatic Connection​

Once confirmed, Pivot automatically receives access to the restaurant's data. No manual credential entry is required.

Tip: If the customer has multiple Toast locations, they can connect multiple locations at once. Each location will sync separately with Pivot.

Toast Partner Connect Subscription​

Toast Partner Connect is required to enable third-party integrations like Pivot.

  • Cost: $25/month per restaurant location (charged by Toast)
  • Billing: This fee is billed directly by Toast, not Pivot
  • Required: Without Partner Connect, the integration cannot be established

Info: Customers should contact Toast directly for questions about Partner Connect billing.

Managing Employees​

Linking Employees to Toast​

Once the integration is set up, customers can link their Pivot employees to their Toast POS profiles:

1. Go to Employee Profile​

Navigate to any employee's profile in Pivot.

2. Find Toast ID Field​

Look for the "Toast ID" field in the employee information section.

3. Search for Employee​

Click on the field and type at least 3 letters of the employee's name as it appears in Toast.

4. Select from Results​

A dropdown will appear with matching employees from Toast. Select the correct employee.

5. Save​

The Toast ID will be saved automatically, linking the two profiles.

Info: The search looks for matches in both first and last names. If an employee isn't found, verify their name is entered correctly in Toast.

Sales Data​

Understanding Sales Synchronization​

Pivot automatically collects sales data from Toast to help with labor cost analysis and reporting:

  • Regular Updates: Sales data is collected automatically throughout the day
  • Per-Employee Attribution: Sales are attributed to individual employees when available
  • Timezone Aware: Data is synced based on the company's timezone setting
  • Historical Data: Past sales data is imported during initial setup

Viewing Sales Data​

Customers can view their Toast sales data in Pivot through:

  1. Dashboard: Sales summaries appear on the main dashboard
  2. Reports: Detailed sales reports under the Analytics section
  3. Labor Cost Analysis: Sales vs. labor cost comparisons in the Payroll section

Time Clock Data​

Time Entry Synchronization​

Pivot imports time clock data from Toast for accurate payroll processing:

  • Clock In/Out Times: Employee punch times are synced automatically
  • Regular and Overtime Hours: Hours are categorized as reported by Toast
  • Job Codes: Position information is included when available

Note: Time clock data sync frequency depends on your Pivot plan configuration.

Disconnecting the Integration​

Option 1: Disconnect from Pivot​

Customers can remove the integration directly from Pivot:

1. Go to Settings​

Navigate to Account Settings → Integrations.

2. Find Toast​

Locate the Toast card in the POS Systems section.

3. Click Disconnect​

Click the "Disconnect" button on the Toast card.

4. Confirm​

Confirm the disconnection when prompted.

Option 2: Remove from Toast Web​

Customers can also remove the integration from Toast:

1. Access Toast Web​

Log into Toast Web and go to Integrations → Integration management → My Integrations.

2. Find Pivot​

Locate Pivot in the list of installed integrations.

3. Remove​

Click the remove or disconnect option. Pivot will be notified automatically.

Warning: Disconnecting the integration will stop all data synchronization. Historical data already in Pivot will remain, but no new data will be imported.

Troubleshooting Common Issues​

Integration Not Appearing in Toast​

If customers cannot find Pivot in Toast's integration marketplace:

  • Verify they have an active Toast Partner Connect subscription
  • Ensure they have the Account Admin > Manage Integrations permission
  • Contact Toast support to verify Partner Connect is enabled for their account

If employees aren't found when searching:

  • Verify employees exist in the Toast POS system
  • Check that names are spelled correctly
  • Ensure the integration shows as "Connected" in settings
  • Wait a few minutes for initial sync if just connected

Sales Data Not Updating​

If sales aren't appearing in Pivot:

  • Confirm transactions exist in Toast for that time period
  • Check the integration status in Account Settings
  • Verify the company timezone is set correctly in both systems
  • Allow time for the sync cycle to complete

"Permission Denied" Errors​

If access errors occur:

  • Verify the integration is still active in Toast Web
  • Check that the restaurant location hasn't been removed from the integration
  • Re-enable the integration from Toast if needed

Integration Shows as Disconnected​

If the integration appears disconnected:

  • Check if it was removed from Toast Web
  • Verify the Toast account is still active
  • Verify Toast Partner Connect subscription is active
  • Re-add the integration from Toast Web if needed

Frequently Asked Questions​

Can I connect multiple Toast locations?​

Yes, customers can connect multiple Toast locations during setup. Each location syncs separately with Pivot, allowing for multi-location management.

How far back can I import sales data?​

Pivot can import historical sales data from Toast. The exact timeframe depends on Toast's data retention and your Pivot plan.

Do I need to map all employees?​

Yes, it's recommended to map all active employees for accurate reporting and payroll export.

What happens to my data if I disconnect?​

All historical data remains in Pivot. Only new data synchronization stops. You can reconnect anytime to resume syncing.

Is there an additional cost for the Toast integration?​

Toast charges $25/month per location for Partner Connect (required for any third-party integration). Pivot does not charge extra for the Toast integration beyond your regular subscription.

What data does Pivot access from Toast?​

Pivot accesses employee roster, time clock entries, and sales/order data. Pivot does not access payment card information or other sensitive financial data.

Getting Help​

If customers need additional assistance:

  • For Toast issues: Contact Toast support directly
  • For Pivot issues: Contact the dev team
  • For integration setup: Follow this guide or contact Pivot support
  • Toast Partner Connect questions: Contact Toast billing support

Note: Remember that the integration requires an active Toast Partner Connect subscription and proper permissions in Toast to function properly.