Managing VTEX gift cards

Learn how to manage VTEX native gift cards using the GiftCard API.

9 min read

This guide describes how to manage VTEX native gift cards from the VTEX gift card provider through the GiftCard API. With this API, you can perform the following actions:

Create a VTEX gift card
View VTEX gift card details
Create VTEX gift card transactions
Viewing VTEX gift card transactions
Cancel a VTEX gift card transaction

You can also manage VTEX gift cards using the VTEX Admin. For more information, see Setting up Gift Cards.

Before you begin

Make sure you meet the following requirements:

Requirement	Description
Authentication credentials	All GiftCard API requests require an `X-VTEX-API-AppKey` and an `X-VTEX-API-AppToken` header. For more information, see Authentication.
Permissions	The application key must be associated with a role that includes the Gift card full access License Manager resource. Without it, requests return a `403` status code.
Customer profile ID	Every gift card is issued to a customer. To create one, you need the customer's `profileId`. You can use the customer's registered email or the `userId` value stored in Master Data.
API client	You can use any HTTP client, such as cURL or Postman, to send the requests in this guide.

The examples in this guide use the account name cosmetics2 in response payloads. Replace accountName and environment in request URLs with your own store values.

Creating a VTEX gift card

To create a VTEX gift card, you can use the Create GiftCard endpoint. In this request, you must send the information of the gift card you want to create.

POST

https://{accountName}.{environment}.com.br/api/giftcards

The request body accepts the following fields:

Field	Required	Description
`relationName`	Yes	Identifies the relationship between the customer and the store. This value must be different for each gift card.
`expiringDate`	Yes	Sets the gift card expiration date in ISO 8601 format (`YYYY-MM-DDThh:mm:ss.fff`).
`caption`	Yes	Describes the gift card and identifies the loyalty program associated with it.
`profileId`	Yes	Identifies the customer, as registered in Master Data.
`currencyCode`	No	Sets the gift card currency in ISO 4217 format. If you omit this field, the gift card behaves as it would in a single-currency store.
`restrictedToOwner`	No	Defines whether the gift card can be used only by the customer identified in `profileId` (`true`) or not (`false`).
`multipleCredits`	No	Defines whether the gift card balance can be changed (`true`) or not (`false`). Set this field to `true` to allow the credit and debit transactions described in Creating VTEX gift card transactions.
`multipleRedemptions`	No	Defines whether the gift card can be used in multiple purchases until its balance is completely used (`true`) or not (`false`).

Request body


_10{
_10  "relationName": "loyalty-program-test",
_10  "expiringDate": "2027-01-01T00:00:00",
_10  "caption": "VTEX Loyalty Test",
_10  "profileId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff",
_10  "restrictedToOwner": false,
_10  "currencyCode": "USD",
_10  "multipleCredits": true,
_10  "multipleRedemptions": false
_10}

The endpoint returns some of the previously sent details and new information about the created gift card, such as:

"id": Gift card identification, composed of the customer's profileId and a sequential number, separated by an underscore.
"redemptionCode": Code the shopper enters at checkout to activate the gift card. It has a minimum of 6 characters.
"redemptionToken": Token used to validate the gift card. This value is required when creating a gift card transaction.
"balance": Gift card balance.
"emissionDate": Gift card issue date.
"transactions": URL of the gift card transactions resource.

Store the redemptionCode and redemptionToken values returned in this response. The Create GiftCard Transaction endpoint requires both of them in the request body.

Response body


_15{
_15    "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_15    "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_15    "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_15    "balance": 0.0000,
_15    "relationName": "loyalty-program-test",
_15    "emissionDate": "2026-09-08T16:20:01.047Z",
_15    "expiringDate": "2027-01-01T00:00:00",
_15    "caption": "VTEX Loyalty Test",
_15    "currencyCode": "USD",
_15    "discount": false,
_15    "transactions": {
_15        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"
_15    }
_15}

You can also access the VTEX Admin (Promotions > Gift Cards) to confirm that the new gift card was created.

${"base64":" ","img":{"width":1816,"height":203,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":71810,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Payments/gift-cards/managing-vtex-gift-cards_1.png"}}$

All gift cards created via API have no balance (value 0). You can add balance amounts to new gift cards through the Create GiftCard Transaction endpoint or the VTEX Admin.

Viewing VTEX gift card details

To check details about a specific gift card, you can use the Get GiftCard by ID endpoint. In this request, you must send the gift card identification (giftCardId) as a path parameter.

The following example uses gift card 92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74:

GET

https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74

Response body


_15{
_15    "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_15    "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_15    "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_15    "balance": 0.0000,
_15    "relationName": "loyalty-program-test",
_15    "emissionDate": "2026-09-08T16:20:01.047Z",
_15    "expiringDate": "2027-01-01T00:00:00",
_15    "caption": "VTEX Loyalty Test",
_15    "currencyCode": "USD",
_15    "discount": false,
_15    "transactions": {
_15        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"
_15    }
_15}

You can also check the information of a VTEX gift card using the VTEX Admin. For more information, go to Promotions > Gift Cards > Search or Filter Results.

Creating VTEX gift card transactions

A gift card transaction is a record of an operation that changes the gift card balance, such as a purchase or a refund. To change balance values, you can use the Create GiftCard Transaction endpoint.

The following sections simulate these changes to the balance of gift card 92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74:

Add 500 USD
Remove 120 USD

Adding balance to a gift card

You can use the Create GiftCard Transaction endpoint to add balance to a gift card. In this request, you must send the gift card identification (giftCardId) as a path parameter.

POST

https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions

To add 500 USD to the balance, send Credit in the operation field and 500 in the value field.

Request body


_10{
_10  "operation": "Credit",
_10  "value": 500,
_10  "description": "Opening balance",
_10  "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_10  "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_10  "requestId": "1"
_10}

Response body


_10{
_10    "cardId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_10    "id": "465f2d7370f349879f4c194ac81d8e98",
_10    "_self": {
_10        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98"
_10    }
_10}

The id field returns the transaction identification, which you need to check or cancel that transaction later.

To confirm the new gift card balance, use the Get GiftCard by ID endpoint or the VTEX Admin.

Response body


_15{
_15    "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_15    "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_15    "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_15    "balance": 500.0000,
_15    "relationName": "loyalty-program-test",
_15    "emissionDate": "2026-09-08T16:20:01.047Z",
_15    "expiringDate": "2027-01-01T00:00:00",
_15    "caption": "VTEX Loyalty Test",
_15    "currencyCode": "USD",
_15    "discount": false,
_15    "transactions": {
_15        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"
_15    }
_15}

In the VTEX Admin, the gift card shows the updated balance:

${"base64":" ","img":{"width":1817,"height":199,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":73771,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Payments/gift-cards/managing-vtex-gift-cards_2.png"}}$

Removing balance from a gift card

To remove balance from a gift card, you must also use the Create GiftCard Transaction endpoint and send the gift card identification (giftCardId) as a path parameter.

POST

https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions

To remove 120 USD from the balance, send Debit in the operation field and 120 in the value field.

Request body


_10{
_10  "operation": "Debit",
_10  "value": 120,
_10  "description": "Payment of order 5555",
_10  "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_10  "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_10  "requestId": "2"
_10}

Response body


_10{
_10    "cardId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_10    "id": "c2b69a5990404a11b26888964bed3868",
_10    "_self": {
_10        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/c2b69a5990404a11b26888964bed3868"
_10    }
_10}

Whenever you create a new transaction, you must send a requestId different from the ones previously used for that gift card. Transactions that have a requestId value previously used on the same gift card aren't completed. For example: after creating the first credit transaction, in which you used the value 1 for requestId, you create a debit transaction with requestId equal to 2. Any other transaction for this gift card must be created with values different from 1 and 2 in the requestId.

To confirm the new gift card balance, use the Get GiftCard by ID endpoint or the VTEX Admin.

Response body


_15{
_15    "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_15    "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_15    "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_15    "balance": 380.0000,
_15    "relationName": "loyalty-program-test",
_15    "emissionDate": "2026-09-08T16:20:01.047Z",
_15    "expiringDate": "2027-01-01T00:00:00",
_15    "caption": "VTEX Loyalty Test",
_15    "currencyCode": "USD",
_15    "discount": false,
_15    "transactions": {
_15        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"
_15    }
_15}

In the VTEX Admin, the gift card shows the balance after the debit transaction:

${"base64":" ","img":{"width":1819,"height":200,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":73925,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Payments/gift-cards/managing-vtex-gift-cards_3.png"}}$

Viewing VTEX gift card transactions

You can use the List All GiftCard Transactions endpoint to check all transactions performed on a gift card. In this request, you must send the gift card identification (giftCardId) as a path parameter.

GET

https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions

The following response body shows information from the two transactions created in the previous sections:


_16[
_16    {
_16        "cardId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_16        "id": "c2b69a5990404a11b26888964bed3868",
_16        "_self": {
_16            "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/c2b69a5990404a11b26888964bed3868"
_16        }
_16    },
_16    {
_16        "cardId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_16        "id": "465f2d7370f349879f4c194ac81d8e98",
_16        "_self": {
_16            "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98"
_16        }
_16    }
_16]

If you use this endpoint to request details for a new gift card that doesn't contain transactions yet, the response body is empty.

Accessing information from a gift card transaction

To get information about a specific gift card transaction, you can use the Get GiftCard Transaction by ID endpoint. In this request, you must send the gift card identification (giftCardId) and the transaction identification (transactionId) as path parameters.

The transactionId value used in this request is the same id value obtained from the response body of the List All GiftCard Transactions endpoint. For more information, see the Viewing VTEX gift card transactions section.

The following example uses gift card 92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74 and the credit transaction 465f2d7370f349879f4c194ac81d8e98.

GET

https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98

Response body


_16{
_16    "value": 500.0,
_16    "description": "Opening balance",
_16    "date": "2026-09-08T16:25:12.331Z",
_16    "requestId": "1",
_16    "settlement": {
_16        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98/settlements"
_16    },
_16    "cancellation": {
_16        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98/cancellations"
_16    },
_16    "authorization": {
_16        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98/authorization"
_16    },
_16    "operation": "Credit"
_16}

The settlement, cancellation, and authorization objects return the URLs of the resources related to that transaction:

Object	Description
`settlement`	Points to the settlements of the transaction. Use Settle GiftCard Transaction to create a settlement, or List All GiftCard Transaction Settlements to retrieve them.
`cancellation`	Points to the cancellations of the transaction. Use Cancel GiftCard Transaction to cancel the transaction, cancel an item reservation, or create a refund.
`authorization`	Points to the authorization data of the transaction. Use Get GiftCard Transaction Authorization to retrieve it.

Canceling a VTEX gift card transaction

To partially or completely cancel a value assigned in a transaction (credit or debit), you can use the Cancel GiftCard Transaction endpoint. In this request, you must send the gift card identification (giftCardId) and the transaction identification (transactionId) as path parameters.

The transactionId value used in this request is the same id value obtained from the response body of the List All GiftCard Transactions endpoint. For more information, see the Viewing VTEX gift card transactions section.

The following example partially cancels the debit transaction c2b69a5990404a11b26888964bed3868. The transaction value is 120 USD and the canceled amount is 20 USD. The gift card used is 92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74, with a current balance of 380 USD.

POST

https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/c2b69a5990404a11b26888964bed3868/cancellations

To cancel the amount of 20 USD in the debit transaction, send 20 in the value field.

Request body


_10{
_10  "value": 20,
_10  "requestId": "3"
_10}

Response body


_10{
_10    "oid": "a1e7edfb72d74bfa960cdbc2eb9471ce",
_10    "value": 20.0,
_10    "date": "2026-09-08T17:28:39.721Z"
_10}

To confirm the new gift card balance, use the Get GiftCard by ID endpoint or the VTEX Admin.

Response body


_15{
_15    "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",
_15    "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a",
_15    "redemptionCode": "COCW-OZYZ-BEXN-TIMU",
_15    "balance": 400.0000,
_15    "relationName": "loyalty-program-test",
_15    "emissionDate": "2026-09-08T16:20:01.047Z",
_15    "expiringDate": "2027-01-01T00:00:00",
_15    "caption": "VTEX Loyalty Test",
_15    "currencyCode": "USD",
_15    "discount": false,
_15    "transactions": {
_15        "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"
_15    }
_15}

In the VTEX Admin, the gift card shows the balance after the partial cancellation:

${"base64":" ","img":{"width":1817,"height":195,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":72401,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Payments/gift-cards/managing-vtex-gift-cards_4.png"}}$

When a debit transaction is canceled, the canceled amount is credited to the total gift card balance. Likewise, when a credit transaction is canceled, the canceled amount is debited from the total gift card balance.

Before you begin.css-17dhml5{min-width:18px;min-height:18px;width:18px;height:18px;}

Creating a VTEX gift card

Viewing VTEX gift card details

Creating VTEX gift card transactions

Adding balance to a gift card

Removing balance from a gift card

Viewing VTEX gift card transactions

Accessing information from a gift card transaction

Canceling a VTEX gift card transaction

Learn more

Before you begin