Sign in

v1

latestSwagger 2.02026-08-0613565.6 KB

Provide information on a loyalty transaction

Provides information about a loyalty transaction processed by the Toast platform. The transaction information in the message body is intended to allow a loyalty provider to perform corresponding operations on the loyalty account, maintained by that provider.

You define the endpoint name for this implementation. The Toast POS system makes requests to the REST path that you supply during integration setup.

Each POST request to the endpoint includes a Toast-Transaction-Type header parameter value to indicate the type of loyalty transaction it represents. The possible transaction types are:

  • Inquire to get information about a given loyalty account given the items currently on the check.
  • Search for a loyalty account.
  • Signup to create a new loyalty account.
  • Redeem offers.
  • Accrue rewards based on a given check.
  • Reverse a previous redeem or accrue transaction.

The LoyaltyTransaction object in the message body includes a set of information that is specific for each transaction type.

The response time for a loyalty transaction request must be less than 500ms on average. A response time of greater than 5000ms will be considered a timeout and will be retried. There is a limit on the number of retries which depends on the context of the call.

All loyalty transactions must be considered idempotent. The implementation must handle multiple requests with the same Toast-Transaction-GUID and the same loyaltyIdentifier.

post/yourendpointname

Headers

Toast-Transaction-GUIDstring

A unique identifier of the loyalty transaction, defined by the Toast POS system.

Toast-Restaurant-External-IDstring

The unique identifier of the restaurant, defined by the Toast POS system.

Toast-Transaction-Type'LOYALTY_INQUIRE' | 'LOYALTY_SEARCH' | 'LOYALTY_SIGNUP' | 'LOYALTY_REDEEM' | 'LOYALTY_ACCRUE' | 'LOYALTY_REVERSE' | 'LOYALTY_TRANSFER'

The type of loyalty transaction that occurred. Values are:

<ul> <li>LOYALTY_INQUIRE</li> <li>LOYALTY_SEARCH</li> <li>LOYALTY_SIGNUP</li> <li>LOYALTY_REDEEM</li> <li>LOYALTY_ACCRUE</li> <li>LOYALTY_REVERSE</li> <li>LOYALTY_TRANSFER</li> </ul>
Authorizationstring

A JSON Web Token (JWT) that you can use to authenticate the request. Verify the token using the public key that you get from the Toast user management service.

Request body

toastTransactionType'LOYALTY_INQUIRE' | 'LOYALTY_SEARCH' | 'LOYALTY_SIGNUP' | 'LOYALTY_REDEEM' | 'LOYALTY_ACCRUE' | 'LOYALTY_REVERSE' | 'LOYALTY_TRANSFER'

The transaction type that is included in the header is duplicated here in the body of the request.

Response

OK. The transactionStatus value of the LoyaltyTransactionResponse object is ACCEPT.

transactionStatus'ACCEPT' | 'ERROR_INVALID_TOAST_TRANSACTION_TYPE' | 'ERROR_ACCOUNT_INVALID' | 'ERROR_INVALID_INPUT_PROPERTIES' | 'ERROR_TRANSACTION_DOES_NOT_EXIST' | 'ERROR_INVALID_TOKEN' | 'ERROR_TRANSACTION_CANNOT_BE_REVERSED' | 'ERROR_INVALID_RESTAURANT' | 'ERROR_INVALID_TRANSFER' | 'ERROR_ALREADY_REGISTERED'

Indicates the result of a loyalty transaction, reported by the loyalty service provider. Possible values are:

<ul> <li>`ACCEPT` - The loyalty service provider processed the transaction successfully.</li> <li>`ERROR_INVALID_TOAST_TRANSACTION_TYPE` - The requested Toast-Transaction-Type is not valid.</li> <li>`ERROR_ACCOUNT_INVALID` - The loyalty account is not recognized or is not valid at the current restaurant.</li> <li>`ERROR_INVALID_INPUT_PROPERTIES` - The specified JSON properties in the request body are not valid.</li> <li>`ERROR_TRANSACTION_DOES_NOT_EXIST` - The transaction that is being requested to be reversed does not exist. Only occurs on a `LOYALTY_REVERSE` transaction.</li> <li>`ERROR_INVALID_TOKEN` - The token supplied in the `Authorization` header field is invalid or cannot be validated.</li> <li>`ERROR_TRANSACTION_CANNOT_BE_REVERSED` - The specified transaction cannot be reversed. Only `LOYALTY_REDEEM` and `LOYALTY_ACCRUE` transactions can be reversed.</li> <li>`ERROR_INVALID_RESTAURANT` - The restaurant specified by the `Toast-Restaurant-External-ID` is invalid.</li> <li>`ERROR_INVALID_TRANSFER` - The cards that is being requested to be Transfer could not be completed.</li> <li>`ERROR_ALREADY_REGISTERED` - The phone number or email address used is already registered to a different account. Only occurs on a `LOYALTY_SIGNUP` transaction.</li> </ul>
All 1 operations