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

Request
header Parameters
Authorization
string

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.

Toast-Restaurant-External-ID
string

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

Toast-Transaction-GUID
string

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

Toast-Transaction-Type
string

The type of loyalty transaction that occurred. Values are:

  • LOYALTY_INQUIRE
  • LOYALTY_SEARCH
  • LOYALTY_REDEEM
  • LOYALTY_ACCRUE
  • LOYALTY_REVERSE
  • LOYALTY_TRANSFER
Enum: "LOYALTY_INQUIRE" "LOYALTY_SEARCH" "LOYALTY_REDEEM" "LOYALTY_ACCRUE" "LOYALTY_REVERSE" "LOYALTY_TRANSFER"
Request Body schema: application/json

A LoyaltyTransaction object containing information about the loyalty transaction that the Toast POS system processed.

object (TransactionInformationCheck)

Information needed to complete an inquire, redeem, or accrue transaction. Included if the toastTransactionType is one of LOYALTY_INQUIRE, LOYALTY_REDEEM, or LOYALTY_ACCRUE, absent otherwise.

object (TransactionInformationReverse)

Information needed to complete a reverse transaction. Included if the toastTransactionType is LOYALTY_REVERSE, absent otherwise.

object (TransactionInformationSearch)

Information needed to complete a search transaction. Included if the toastTransactionType is LOYALTY_SEARCH, absent otherwise.

toastTransactionType
string

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

Enum: "LOYALTY_INQUIRE" "LOYALTY_SEARCH" "LOYALTY_REDEEM" "LOYALTY_ACCRUE" "LOYALTY_REVERSE" "LOYALTY_TRANSFER"
object (TransactionInformationTransfer)

Information needed to complete a transfer transaction. Included if the toastTransactionType is LOYALTY_TRANSFER, absent otherwise.

Responses
200

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

400

Bad request. The transactionStatus value of the LoyaltyTransactionResponse object is one of:

  • 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
500

Internal server error.

post/yourendpointname
Request samples
application/json
{
  • "toastTransactionType": "LOYALTY_INQUIRE",
  • "searchTransactionInformation": {
    },
  • "checkTransactionInformation": {
    },
  • "reverseTransactionInformation": {
    },
  • "transferTransactionInformation": {
    }
}
Response samples
application/json
{
  • "transactionStatus": "ACCEPT",
  • "searchResponse": {
    },
  • "checkResponse": {
    },
  • "transferResponse": {
    }
}