Building a loyalty integration

Follow the steps below to build a loyalty integration with the Toast platform.

  1. Setup

    Complete initial integration setup 

    Review and implement the instructions on the Getting Started section.

    Submit endpoint to Toast 

    Your loyalty requires a single endpoint. Submit your test environment endpoint to Toast support so they can set up the endpoint in the Toast sandbox environment.

    Review initial information 

    First, review the loyalty integration overview and POS workflow to understand the flow of information in a loyalty integration.

    Decide discount types you will support 

    Familiarize yourself with reward processing information and decide whether you will support check-level discounts, item-level discounts, or both.

    Perform an initial test 

    Use the integration verification tool to send a Search request to your endpoint. Review the structure, format, and headers of this request to familiarize yourself with loyalty in Toast.

    If your integration supports item-level discounts, you must use the menus API to save menu information so that restaurant administrator can map discounts from your service to menu items in the Toast platform.

    Decide loyalty identifier structure 

    Your integration needs to assign a loyaltyIdentifier for each loyalty account in your system. Decide the format of this identifier (such as a UUID). Loyalty identifiers cannot contain personal information such as email addresses or phone numbers.

  2. Success responses

    Develop success workflow 

    Review all loyalty transaction types. For all transaction types, develop successful responses that contain a 200 HTTP response status code and a transactionStatus of ACCEPT.

    Validate that you send timely responses 

    Ensure that your endpoint adheres to Toast loyalty latency requirements. This allows the Toast platform to correctly understand how you processed the transaction in your system.

    If your endpoint does not adhere to timeout requirements, guests will see an error message on the POS that instructs them to contact your support team.

    Handle transactions without loyalty identifiers 

    The loyaltyIdentifier value may be null on LOYALTY_ACCRUE and LOYALTY_REVERSE requests. If the loyaltyIdentifier on these transactions is null and the transaction is otherwise structured correctly, your endpoint must return a 200 HTTP response status code and a transactionStatus of ACCEPT.

    Validate endpoint idempotence 

    Ensure that your endpoint is idempotent using the Toast-Transaction-GUID header on the transactions you receive. If two requests contain the same Toast-Transaction-GUID, they are the same request. See Network failure and idempotence for more information about transaction retries and idempotence.

  3. Failure responses

    Handle unknown restaurants 

    Your system must maintain an allowlist of restaurant GUIDs that your integration recognizes.

    If the Toast-Restaurant-External-ID header in a loyalty transaction contains a restaurant GUID that is not on your allowlist, your endpoint must return a 400 HTTP response status code and a transactionStatus of ERROR_INVALID_RESTAURANT.

    Handle invalid authentication tokens 

    Your endpoint must validate that loyalty transactions came from the Toast production environment.

    If your loyalty authentication process determined that a transaction came from somewhere other than the Toast production environment, your endpoint must return a 400 HTTP response status code and a transactionStatus of ERROR_INVALID_TOKEN.

    Use the integration verification tool to test authentication against your production endpoint, because this tool submits requests out of the Toast sandbox environment.

    Handle unknown loyalty accounts 

    If you receive a loyalty transaction whose loyaltyIdentifier you do not recognize, your endpoint must return a 400 HTTP response status code and a transactionStatus of ERROR_ACCOUNT_INVALID.

    Handle unexpected information from Toast 

    If you receive unexpected information from the Toast platform, your endpoint must return a 400 HTTP response status code and one of the following values for transactionStatus, depending on the information you receive:

    • ERROR_INVALID_TOAST_TRANSACTION_TYPE

    • ERROR_INVALID_INPUT_PROPERTIES

    • ERROR_TRANSACTION_DOES_NOT_EXIST

    • ERROR_TRANSACTION_CANNOT_BE_REVERSED

    See Error handling for more information.

    Handle unexpected errors in your system 

    If your system has an unexpected error, your endpoint must return a 500 HTTP response status code and a transactionStatus of ERROR. If you send a message in your response, not return any guest personal information in the message.

  4. Test your integration

    Run through the test plan 

    Use the loyalty integration test plan to validate that you correctly handle each test case.

    Review functionality with Toast team 

    Contact the Toast support team about walking through the test plan together. After the Toast team confirms that your integration is ready to go live, send your production endpoint to the Toast support team.

    Plan for onboarding 

    Set up the allowlist of restaurant GUIDs you support and prepare a sample email for requesting new integration connections. The Toast support team will supply you with a guide for integration enablement. Bookmark this page for distribution to customers to help them understand the integration onboard process.

Congratulations on building a loyalty integration, allowing customers to use your loyalty functionality in their Toast POS workflows.