Review and implement the instructions in How to build a Toast integration.

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

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

Familiarize yourself with reward processing information.

Decide whether you will support check-level discounts, item-level discounts, or both.

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

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.

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.

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.

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.

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.

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.

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.

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.

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:

See Error handling for more information.

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.

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

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.

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 Toast Central article to distribute to customers to help them understand the integration onboarding process.