For businesses utilizing Toast’s platform, integrating gift card functionality is crucial. This article delves into how to check your Toast Gift Card Balance using the Gift Card Integration API. While there isn’t a direct “check balance” transaction type, understanding the GIFTCARD_REDEEM request and response provides valuable insight into managing and verifying gift card balances.
This guide will walk you through an example of a gift card API transaction request and response, focusing on how the balance is reflected in these interactions. This information is vital for developers looking to implement or troubleshoot gift card integrations with Toast.
Decoding the Gift Card Redeem Transaction Request
The following code block illustrates a sample API request for a GIFTCARD_REDEEM transaction. Although primarily used for redeeming a gift card, analyzing this request helps understand how gift card information is structured within the Toast API.
> Content-Type: application/json
> Toast-Transaction-Type: GIFTCARD_REDEEM
> Toast-Restaurant-External-ID: 76cb1b05-cb1e-4adf-863a-b2a94a5ecdcf
> Toast-Transaction-GUID: 63fdc064-c97e-431f-9cb2-0699c6488237
> Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxM jM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.Sf lKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
{
"redeemTransactionInformation":{
"redeemedValue":11.80,
"giftCardIdentifier":"231952736",
"checkIdentifier":"41531b0c-ad11-4c11-9ad6-29ba76925a13",
"isCashOut":false
}
}| Parameter | Description | |
|---|---|---|
Content-Type: application/json |
Specifies that the request body is in JSON format. | |
Toast-Transaction-Type: GIFTCARD_REDEEM |
Indicates the type of gift card transaction being performed, in this case, a redemption. Refer to the Gift card transaction types documentation for other types. | |
Toast-Restaurant-External-ID: 76cb1b05-cb1e-4adf-863a-b2a94a5ecdcf |
Identifies the specific restaurant location processing the gift card transaction within the Toast platform. This ID is provided by the Toast integrations team. | |
Toast-Transaction-GUID: 63fdc064-c97e-431f-9cb2-0699c6488237 |
A unique identifier for this particular transaction request. It’s crucial to maintain this ID for potential future GIFTCARD_REVERSE transactions. See Gift card transaction types for more details. |
|
Authorization |
The JWT authentication token used to verify the request’s origin from Toast and ensure its integrity. More information is available in the Gift card integration authentication documentation. | |
GiftCardTransaction object (JSON Body) |
The main body of the request, containing details about the gift card transaction. For a comprehensive understanding of the GiftCardTransaction object, consult the gift card integration API reference documentation. |
|
redeemTransactionInformation |
As this is a GIFTCARD_REDEEM transaction, this object contains specific details related to the redemption. |
|
redeemedValue: 11.80 |
Indicates the amount being redeemed from the gift card balance, in this example, $11.80. This represents the value used for a purchase. | |
giftCardIdentifier: "231952736" |
The unique identifier for the gift card being used in the transaction. This is how the system identifies the specific gift card and its associated balance. |
Analyzing the Gift Card Redeem Transaction Response for Balance Information
Upon processing the GIFTCARD_REDEEM request, the API returns a response containing the updated gift card balance. This response is key to understanding how to indirectly check the Toast gift card balance.
{
"transactionStatus":"ACCEPT",
"redeemResponse":{
"currentBalance":60.29,
"redeemedValue":1
}
}| Parameter | Description | |
|---|---|---|
GiftCardTransactionResponse object (JSON Body) |
The response body, a JSON object, providing details about the processed gift card transaction. For detailed information on the GiftCardTransactionResponse object, refer to the gift card integration API reference documentation. |
|
transactionStatus: "ACCEPT" |
Indicates the outcome of the transaction processing attempt. “ACCEPT” signifies successful processing. For other possible statuses, see Response status types. | |
redeemResponse |
Present because the transaction type is GIFTCARD_REDEEM, this object holds redemption-specific information. |
|
currentBalance: 60.29 |
Crucially, this parameter shows the remaining balance on the gift card after the transaction. In this example, the balance is $60.29. This is how you ascertain the toast gift card balance after a redeem transaction. | |
redeemedValue: 1 |
Indicates the amount deducted from the gift card balance during this specific transaction. |
Conclusion
While a dedicated “check balance” API call might be absent, the Toast Gift Card Integration API effectively communicates the gift card balance through transaction responses. By understanding the structure of the GIFTCARD_REDEEM request and, more importantly, the currentBalance field in the response, developers can confidently manage and verify toast gift card balances within their integrated systems. This example provides a foundational understanding for anyone working with Toast’s gift card API and needing to ascertain the toast gift card balance programmatically.
