Follow the steps below to build a loyalty integration with the Toast platform, which allows customers to use your loyalty functionality in their Toast POS workflows.
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.
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:
-
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.
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.