Welcome to the Toast integration community! Here's how to get started building your Toast integration. We look forward to seeing what you build!
Before you build your integration, be sure you're on the distribution list for release notes and status updates.
Subscribe to updates on this page.
To familiarize yourself with Toast APIs, download our collection of example API requests.
To get an authentication token, plug in your credentials and the sandbox hostname. You get your credentials and the sandbox hostname from the Toast integrations team when you start to build your integration.
For more information, see Integration partnership process.
Use these instructions to use the authentication API to get your first authentication token.
Your integration should request a new authentication token during the last minute the original token is valid (less than 60 seconds before the original token expires).
For more information, see Refreshing authentication tokens.
If you use a partner API client
Contact the Toast integrations team with your URL for the partners webhook. Review the webhook documentation.
Use this webhook to receive real-time notifications when:
-
Your integration is added or removed.
-
Restaurants update the location and group ID fields for your integration.
The webhook should be your primary mechanism to understand who is connected to your integration, with the partners API as a backup.
If you receive a notification that a restaurant has removed your integration, stop all API requests for that restaurant location.
In addition, poll the /restaurants endpoint of the
partners API
to retrieve a list of all restaurants connected to your integration.
Programmatically poll this endpoint a few times per day using the
lastModified query parameter to see if any new restaurants
have connected to your integration since you last evaluated the
list.
If you use a restaurant management group API client
Use the restaurant GUID and restaurant group GUID to retrieve from the /groups endpoint a list of all restaurants in your restaurant management group.
You get the restaurant GUID and the restaurant group GUID from the Toast integrations team when you begin to build your integration.
If you add restaurants to your management group in the future, the endpoint will include the new restaurant locations in the list.
To avoid receiving rate limit errors when you call Toast APIs, throttle your requests so they stay within Toast API rate limits.
To resolve any issues in your integration, you must know when errors occur and have information to help determine the causes of those errors.
If you cannot successfully submit data to the Toast platform or retrieve data from it, your integration may not function as intended, which will frustrate users of your integration.
It is critical that you have a strong error management and resolution process.
If you receive the same error when you make the same API request multiple times, you should stop making that API request.
Your integration should have an error threshold, after which you stop submitting the same API call repeatedly and instead raise an alert in your own system to investigate the error.
After your integration goes live, you need to be equipped to handle planned and unplanned downtimes of the Toast platform.
Use the API downtime guidelines to create your downtime procedures before you need them.
If there is an issue with the integration, instruct mutual customers to contact your support team rather than the Toast support team. Because you build and maintain your integration with Toast, we ensure a smooth customer experience when mutual customers contact your team with questions and issues about your integration.
Your documentation should also instruct restaurants about how to do any necessary onboarding steps within your own administrative tools and within Toast.