Building a Toast integration

Welcome to the Toast integration community! Here's how to get started building your Toast integration.

  1. Initial setup

    Sign up for updates 

    Subscribe to updates on this page to be added to the distribution list for release notes and status updates.

    Download example API requests 

    To 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.

  2. Authentication

    Note

    This section does not apply to the gift card API or the loyalty API.

    Get an authentication token 

    Use these instructions to get your first authentication token using the authentication API.

    Refresh your 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.

  3. Restaurant connections

    Note

    This section does not apply to the gift card API or the loyalty API.

    If you are using a partner API client 

    Contact 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 the lastModified 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 client 

    Use 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.

  4. Rate limits

    Note

    This section does not apply to the gift card API or the loyalty API.

    Throttle for rate limits 

    To avoid receiving rate limit errors when you call Toast APIs, throttle your requests so they stay within Toast API rate limits.

  5. Error management

    Determine your error logging process 

    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.

    Use a halting mechanism 

    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.

    Plan downtime procedures 

    After 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.

  6. Documentation

    Write integration documentation 

    If 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!