Welcome to the Toast integration community! Here's how to get started building your Toast integration.
-
Initial setup
Sign up for updatesSubscribe to updates on this page to be added to the distribution list for release notes and status updates.
Download example API requestsTo familiarize yourself with Toast APIs, download our collection of example API requests. Plug in your credentials and the sandbox hostname to get an authentication token. You get your credentials and the sandbox hostname from the Toast integrations team when you start building your integration. For more information, see Integration Development Process.
-
Authentication
Note
This section does not apply to the gift card API or the loyalty API.
Get an authentication tokenUse these instructions to get your first authentication token using the authentication API.
Refresh your authentication tokenYour 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.
-
Restaurant connections
Note
This section does not apply to the gift card API or the loyalty API.
If you are using a partner API clientContact the Toast integrations team with your URL for the partners webhook and review webhook documentation. Use this webhook to receive real-time notifications when your integration is added or removed or when restaurants update the location and group ID fields for your integration. The webhook should be your primary mechanism for understanding 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 thelastModified
query parameter to see if any new restaurants have connected to your integration since you last evaluated the list.If you are using a restaurant management group API clientUse the restaurant GUID and restaurant group GUID to retrieve a list of all restaurants in your restaurant management group using the /groups endpoint. You get the restaurant GUID and the restaurant group GUID from the Toast integrations team when you begin building your integration. If you add additional restaurants to your management group in the future, the endpoint will include the new restaurant locations in the list.
-
Rate limits
Note
This section does not apply to the gift card API or the loyalty API.
Throttle for rate limitsTo avoid receiving rate limit errors when you call Toast APIs, throttle your requests so they stay within Toast API rate limits.
-
Error management
Determine your error logging processTo 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.
Use a halting mechanismIf 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.
Plan downtime proceduresAfter your integration goes live, you will need to be equipped to handle planned and unplanned downtimes of the Toast platform. Create your downtime procedures before you need them using API downtime guidelines.
-
Documentation
Write integration documentationIf there an issue with the integration, instruct mutual customers to contact your support team rather than the Toast support team. Since 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.
You are now ready to develop your integration's unique functionality. We look forward to seeing what you build!