{ "openapi": "3.0.0", "info": { "title": "GiftCard API", "description": ">ℹ️ Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Gift Card is a payment method configured as a cash value associated with a client. It is used to grant a discount on the value of the order at the store. A Gift Card works as a **payment method**, **not a promotion**.\r\n\r\nIn VTEX's native gift card system, you can choose to create a new gift card either through [Admin VTEX](https://help.vtex.com/en/tutorial/gift-card--tutorials_995) or [API](https://developers.vtex.com/docs/api-reference/giftcard-api#post-/giftcards). However, there are specific conditions to be observed when generating gift cards by one of these two methods.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
SpecificationsAdmin VTEXGiftCard API
Initial valueYou can create gift cards value with any value.All gift cards are generated with no value (balance = 0). After its creation, you need to use Admin VTEX or the Create GiftCard Transaction to add any balance amount.
Ownership restrictionYou can create gift cards with or without a user assigned to them.All gift cards must be created with a profileId associated to them.
User data identificationCustomer ID (data that identifies a specific client, such as CPF/CNPJ in Brazil).profileId (data that identifies a specific client)
Additional SettingsYou can use checkboxes to select whether a gift card will be: Restricted (only a specific customer ID can use this gift card), Reloadable (balance can be changed while it is still active), or Reusable (available for making new purchases with this gift card until its value is completely used up).You can use the following fields to configure the same conditions applied in Admin: restrictedToOwner, multipleRedemptions, and multipleCredits.
\r\n\r\n>⚠️ All GiftCard API endpoints are limited to 500 concurrent requests and 5000 requests per minute.\r\n\r\n## GiftCard API Index\r\n\r\n### Gift Card\r\n\r\n- `POST` [Create GiftCard](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#post-\/giftcards)\r\n- `GET` [Get GiftCard by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#get-\/giftcards\/-giftCardId-)\r\n- `POST` [List All GiftCards](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#post-\/giftcards\/_search)\r\n\r\n### Transaction\r\n\r\n- `POST` [Create GiftCard Transaction](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#post-\/giftcards\/-giftCardId-\/transactions)\r\n- `GET` [Get GiftCard Transaction by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#get-\/giftcards\/-giftCardId-\/transactions\/-transactionId-)\r\n- `GET` [List All GiftCards Transactions](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#get-\/giftcards\/-giftCardId-\/transactions)\r\n- `GET` [Get GiftCard Transaction Authorizations](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#get-\/giftcards\/-giftCardId-\/transactions\/-transactionId-\/authorization)\r\n- `POST` [Cancel GiftCard Transaction](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#post-\/giftcards\/-giftCardId-\/transactions\/-transactionId-\/cancellations)\r\n- `GET` [List All GiftCard Transaction Cancellations](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#get-\/giftcards\/-giftCardId-\/transactions\/-transactionId-\/cancellations)\r\n- `POST` [Settle GiftCard Transaction](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#post-\/giftcards\/-giftCardId-\/transactions\/-transactionId-\/settlements)\r\n- `GET` [List All GiftCard Transactions Settlements](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-api#get-\/giftcards\/-giftCardId-\/transactions\/-transactionId-\/settlements).", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br/api/", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "{accountName}" }, "environment": { "description": "Environment to use. Used as part of the URL.", "default": "{environment}" } } } ], "paths": { "/giftcards": { "post": { "tags": [ "Gift Card" ], "summary": "Create GiftCard", "description": "Creates a gift card for a specific user.\r\n\r\n## Warning\r\n\r\n>ℹ️️ The `redemptionCode` field for a gift card is auto-generated on the creation and cannot be set to an arbitrary value.", "operationId": "CreateGiftCard", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcard.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response" }, "example": { "id": "954", "redemptionToken": "32ScL57220Vapb8pc50HJ3mWH1cl1L8x", "redemptionCode": "***********ASDQ", "balance": 0.0, "relationName": "cardName", "emissionDate": "2014-04-24T20:22:58.163", "expiringDate": "2016-01-01T00:00:00", "caption": "Programa Vtex Fidelidade", "currencyCode":"USD", "transactions": { "href": "cards/954/transactions" } } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}": { "get": { "tags": [ "Gift Card" ], "summary": "Get GiftCard by ID", "description": "Returns information for a specific gift card.", "operationId": "GetGiftCardbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "2" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "id", "redemptionToken", "redemptionCode", "balance", "emissionDate", "expiringDate", "transactions" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "redemptionToken": { "type": "string", "description": "Gift card redemption token." }, "redemptionCode": { "type": "string", "description": "Gift card redemption code." }, "balance": { "type": "number", "description": "Gift card current balance. For newly created gift cards, the balance will be 0.0." }, "emissionDate": { "type": "string", "description": "Gift card emission date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "transactions": { "$ref": "#/components/schemas/Transactions" } } }, "example": { "id": "954", "redemptionToken": "32ScL57220Vapb8pc50HJ3mWH1cl1L8x", "redemptionCode": "***********ASDQ", "balance": 0.0, "emissionDate": "2014-04-24T20:22:58.163", "expiringDate": "2016-01-01T00:00:00", "currencyCode":"USD", "transactions": { "href": "cards/954/transactions" } } } } } }, "deprecated": false } }, "/giftcards/_search": { "post": { "tags": [ "Gift Card" ], "summary": "List All GiftCards", "description": "Returns a list of all gift cards available for a specific cart or client.", "operationId": "SearchGiftCardsfromcartdata", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "REST-Range", "in": "header", "description": "Pagination control. This query variable must follow the format _resources={from}-{to}_.", "required": false, "style": "simple", "schema": { "type": "string", "default": "resources=0-49" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGiftCardusingJSONRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response2" }, "example": { "items": [ { "id": "589", "_self": { "href": "cards/589" } }, { "id": "590", "_self": { "href": "cards/590" } }, { "id": "591", "_self": { "href": "cards/591" } }, { "id": "592", "_self": { "href": "cards/592" } } ], "paging": { "page": 0, "perPage": 10, "total": 4, "pages": 1 } } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions": { "get": { "tags": [ "Transaction" ], "summary": "List All GiftCard Transactions", "description": "Returns the IDs of all transactions performed on a gift card.", "operationId": "GetGiftCardTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "2" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/response3" } }, "example": [ { "id": "268", "_self": { "href": "cards/890/transactions/268" } }, { "id": "269", "_self": { "href": "cards/890/transactions/269" } }, { "id": "270", "_self": { "href": "cards/890/transactions/270" } } ] } } } }, "deprecated": false }, "post": { "tags": [ "Transaction" ], "summary": "Create GiftCard Transaction", "description": "Creates a transaction (credit or debit) to a gift card and authorize the item reservation.", "operationId": "CreateGiftCardTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionRequest" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response3" }, "example": { "id": "2541", "_self": { "href": "providers/VtexGiftCardProvider/cards/890/transactions/2451" } } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}": { "get": { "tags": [ "Transaction" ], "summary": "Get GiftCard Transaction by ID", "description": "Returns a specific transaction for a gift card.", "operationId": "GetGiftCardTransactionbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response5" }, "example": { "value": 140.0, "description": "GiftCardHub", "date": "2023-06-02T18:24:49.252855Z", "requestId": "3", "settlement": { "href": "/cosmetics2/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_70/transactions/faa6831230634c4b8fb897e02ba9c5a1/settlements" }, "cancellation": { "href": "/cosmetics2/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_70/transactions/faa6831230634c4b8fb897e02ba9c5a1/cancellations" }, "authorization": { "href": "/cosmetics2/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_70/transactions/faa6831230634c4b8fb897e02ba9c5a1/authorization" }, "operation": "Credit" } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}/authorization": { "get": { "tags": [ "Transaction" ], "summary": "Get GiftCard Transaction Authorization", "description": "Returns information about a gift card transaction authorization.", "operationId": "GetTransactionAuthorizations", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response6" }, "example": { "oid": "7cf8d7970e1c81d05620e46cceb6819f", "value": 123.4, "date": "2016-01-01T00:00:00" } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}/cancellations": { "get": { "tags": [ "Transaction" ], "summary": "List All GiftCard Transactions Cancellations", "description": "Returns all transactions cancelled for a specific gift card.", "operationId": "GetTransactionCancellations", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/response7" } }, "example": [ { "oid": "239d35b430fc75379db966c1d3670c6f", "value": 13.4, "date": "2016-04-06T00:00:00" }, { "oid": "49f0bad299687c62334182178bfd75d8", "value": 10.4, "date": "2016-05-06T00:00:00" } ] } } } }, "deprecated": false }, "post": { "tags": [ "Transaction" ], "summary": "Cancel GiftCard Transaction", "description": "This request can be used to:\r\n\r\n1. Cancel a transaction for a specific gift card.\r\n\r\n2. Cancel an item's reservation or create a refund.", "operationId": "CancelGiftCardTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b476900c" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GiftCardTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response6" }, "example": { "oid": "239d35b430fc75379db966c1d3670c6f", "value": 17.4, "date": "2016-04-06T00:00:00" } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}/settlements": { "get": { "tags": [ "Transaction" ], "summary": "List All GiftCard Transactions Settlements", "description": "Returns all transactions settlements for a specific gift card.", "operationId": "GetTransactionSettlements", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/response6" } }, "example": [ { "oid": "b8e0c606b2fe543e5b0e639575cd9723", "value": 17.4, "date": "2016-04-06T00:00:00" }, { "oid": "6cb6cd63c16e219b1eee61f2", "value": 10.4, "date": "2016-05-06T00:00:00" } ] } } } }, "deprecated": false }, "post": { "tags": [ "Transaction" ], "summary": "Settle GiftCard Transaction", "description": "Creates a transaction settlement for a specific gift card.", "operationId": "SettleGiftCardTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GiftCardTransactionRequest" }, "example": { "value": 17.4, "requestId": "6360f98eb0cf6fd5afa77e39bba8c20fe5807d8c" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response6" }, "example": { "oid": "b8e0c606b2fe543e5b0e639575cd9723", "value": 17.4, "date": "2016-04-06T00:00:00" } } } } }, "deprecated": false } } }, "components": { "schemas": { "CreateGiftCardRequest": { "type": "object", "required": [ "relationName", "expiringDate", "caption", "profileId" ], "properties": { "relationName": { "type": "string", "description": "Represents the relationship between the client and the store.", "example": "loyalty-program" }, "expiringDate": { "type": "string", "description": "It must be in the format `YYYY-MM-DDThh:mm:ss.fff` (ISO 8601 format).", "example": "2020-09-01T13:15:30Z" }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the gift card.", "example": "rewards program" }, "profileId": { "type": "string", "description": "The client's ID.", "example": "1234" }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217.", "example": "USD" }, "restrictedToOwner": { "type": "boolean", "description": "The gift card can only be used for a specified client's ID.", "example": false }, "multipleCredits": { "type": "boolean", "description": "The gift card balance can be changed.", "example": false }, "multipleRedemptions": { "type": "boolean", "description": "The gift card can be used to make new purchases until its value is completely used.", "example": false } } }, "response": { "type": "object", "required": [ "id", "redemptionToken", "redemptionCode", "balance", "relationName", "emissionDate", "expiringDate", "caption", "transactions" ], "properties": { "id": { "type": "string", "description": "Gift card identification.", "example": "954" }, "redemptionToken": { "type": "string", "description": "Gift card redemption token.", "example": "32ScL57220Vapb8pc50HJ3mWH1cl1L8x" }, "redemptionCode": { "type": "string", "description": "Gift card redemption code.", "example": "***********ASDQ" }, "balance": { "type": "integer", "description": "Gift card current balance. For Gift Cards newly created, the balance will be 0.0.", "example": 0.0 }, "relationName": { "type": "string", "description": "Field to be filled in when it is not necessary to use a loyalty program for the gift card. Observation: A new `relationNamevalue` is required for each new gift card to be created.", "example": "cardName" }, "emissionDate": { "type": "string", "description": "Gift card emission date.", "example": "2014-04-24T20:22:58.163" }, "expiringDate": { "type": "string", "description": "Gift card expiration date.", "example": "2016-01-01T00:00:00" }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the Gift Card.", "example": "Programa Vtex Fidelidade" }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217.", "example": "USD" }, "transactions": { "$ref": "#/components/schemas/Transactions" } } }, "Transactions": { "type": "object", "description": "Transactions information.", "required": [ "href" ], "properties": { "href": { "type": "string", "description": "Gift card resource URL.", "example": "cards/954/transactions" } } }, "GetGiftCardusingJSONRequest": { "type": "object", "required": [ "cart", "client" ], "properties": { "cart": { "$ref": "#/components/schemas/Cart" }, "client": { "$ref": "#/components/schemas/Client" } } }, "Cart": { "type": "object", "required": [ "grandTotal", "relationName", "redemptionCode", "discounts", "shipping", "taxes", "items", "itemsTotal" ], "properties": { "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 182 }, "relationName": { "type": "string", "nullable": true, "description": "Represents the relationship between the client and the store.", "example": null }, "redemptionCode": { "type": "string", "description": "Minimum of six characters.", "example": "BAHD-ASDB-ADQW-ASDQ" }, "discounts": { "type": "integer", "description": "Discounts value.", "example": 20 }, "shipping": { "type": "integer", "description": "Shipping value.", "example": 2 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "description": "Items information." }, "itemsTotal": { "type": "integer", "description": "Total items value.", "example": 200 } } }, "Item": { "type": "object", "required": [ "productId", "id", "refId", "name", "price", "quantity" ], "properties": { "productId": { "type": "string", "description": "Product ID.", "example": "2000000" }, "id": { "type": "string", "description": "The ID of the SKU in VTEX platform.", "example": "2000002" }, "refId": { "type": "string", "description": "Product Reference ID.", "example": "MEV41" }, "name": { "type": "string", "description": "Product name.", "example": "Shoes" }, "price": { "type": "integer", "description": "Product price.", "example": 200 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 } } }, "Client": { "type": "object", "required": [ "id", "email", "document" ], "properties": { "id": { "type": "string", "description": "Customer's identification.", "example": "3b1abc17" }, "email": { "type": "string", "description": "Customer's email address.", "example": "email@domain.com" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "234235" } } }, "response2": { "type": "object", "required": [ "items", "paging" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item1" }, "description": "Items information." }, "paging": { "$ref": "#/components/schemas/Paging" } } }, "Item1": { "type": "object", "required": [ "id", "_self" ], "properties": { "id": { "type": "string", "description": "Item identification.", "example": "589" }, "_self": { "$ref": "#/components/schemas/Self" } } }, "Self": { "type": "object", "description": "Object that carries an auto reference of the transaction (on its API).", "required": [ "href" ], "properties": { "href": { "type": "string", "description": "Gift card resource URL.", "example": "cards/890/transactions/268" } } }, "Paging": { "type": "object", "required": [ "page", "perPage", "total", "pages" ], "properties": { "page": { "type": "integer", "description": "Page number of the gift card list.", "example": 0 }, "perPage": { "type": "integer", "description": "Quantity of gift cards per page.", "example": 10 }, "total": { "type": "integer", "description": "Total of gift cards in the store.", "example": 4 }, "pages": { "type": "integer", "description": "Total number of pages.", "example": 1 } } }, "response3": { "type": "object", "required": [ "id", "_self" ], "properties": { "id": { "type": "string", "description": "Transaction identification.", "example": "268" }, "_self": { "$ref": "#/components/schemas/Self" } } }, "CreateGiftCardTransactionRequest": { "type": "object", "required": [ "operation", "value", "description", "redemptionToken", "redemptionCode", "requestId" ], "properties": { "operation": { "type": "string", "description": "Type of operation. Possible values are: `Debit` or `Credit`.", "example": "Debit" }, "value": { "type": "number", "format": "decimal", "description": "Operation value.", "example": 3 }, "description": { "type": "string", "description": "Description information.", "example": "GiftCardHub" }, "redemptionToken": { "type": "string", "description": "Gift card redemption token.", "example": "b2dac6f2-f365-48cd-82a9-0b376a55557a" }, "redemptionCode": { "type": "string", "description": "Gift card redemption code.", "example": "***********ASDQ" }, "requestId": { "type": "string", "description": "Request identification of the transaction. You need to send a different `requestId` value every time you make a new transaction. If you send the same `requestId`two or more times with a specific `redemptionCode`or `redemptionToken`, the gift card balance will not be updated.", "example": "B56CBE231DEE4E1A859183C1030CE926" }, "orderInfo": { "$ref": "#/components/schemas/OrderInfo" } } }, "OrderInfo": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID.", "example": "v5006128str" }, "sequence": { "type": "integer", "description": "Sequence number.", "example": 5006128 }, "cart": { "$ref": "#/components/schemas/Cart1" }, "clientProfile": { "$ref": "#/components/schemas/ClientProfile" }, "shipping": { "$ref": "#/components/schemas/Shipping" } } }, "Cart1": { "type": "object", "required": [ "items", "grandTotal", "discounts", "shipping", "taxes", "itemsTotal" ], "properties": { "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item2" } }, "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 0 }, "discounts": { "type": "number", "description": "Discounts value.", "example":-7.5 }, "shipping": { "type": "number", "description": "Shipping value.", "example": 7.27 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "itemsTotal": { "type": "number", "description": "Total items value.", "example": 14.99 } } }, "Item2": { "type": "object", "required": [ "id", "productId", "refId", "name", "value", "price", "quantity", "shippingDiscount", "discount", "priceTags" ], "properties": { "id": { "type": "string", "description": "The ID of the SKU in VTEX platform.", "example": "2001023" }, "productId": { "type": "string", "description": "Product ID.", "example": "2000492" }, "refId": { "type": "string", "description": "Product Reference ID.", "example": "35994" }, "name": { "type": "string", "description": "Product name.", "example": "Vaporizador Des. ColC4nia Branco" }, "value": { "type": "number", "description": "Product value.", "example": 14.99 }, "price": { "type": "number", "description": "Product price.", "example": 14.99 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 }, "shippingDiscount": { "type": "integer", "description": "Discount to be applied for the shipping value.", "example": 0 }, "discount": { "type": "number", "description": "Discount applied on item.", "example": -7.5 }, "priceTags": { "type": "array", "description": "Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order.", "items": { "$ref": "#/components/schemas/PriceTag" } } } }, "PriceTag": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Price tag name.", "example": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c" }, "value": { "type": "integer", "description": "Price tag value.", "example": 0 } } }, "ClientProfile": { "type": "object", "description": "Client Profile information.", "required": [ "email", "firstName", "lastName", "document", "phone", "birthDate", "isCorporate" ], "properties": { "email": { "type": "string", "description": "Customer's email address.", "example": "miguel.scott96@yahoo.com.br" }, "firstName": { "type": "string", "description": "Customer's first name.", "example": "miguel" }, "lastName": { "type": "string", "description": "Customer's last name.", "example": "scott" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "02906792063" }, "phone": { "type": "string", "description": "Customer's phone number.", "example": "+551111111111" }, "birthDate": { "type": "string", "description": "Customer's birth date.", "example": "0001-01-01T00:00:00" }, "isCorporate": { "type": "boolean", "description": "`true` if the customer is a legal entity.", "example": false } } }, "Shipping": { "type": "object", "description": "Shipping information.", "required": [ "receiverName", "postalCode", "city", "state", "country", "street", "number", "neighborhood", "complement", "reference" ], "properties": { "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order.", "example": "miguel scott" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "22250040" }, "city": { "type": "string", "description": "City of the shipping address.", "example": "Rio de Janeiro" }, "state": { "type": "string", "description": "State of the shipping address.", "example": "RJ" }, "country": { "type": "string", "description": "Country of the shipping address.", "example": "BRA" }, "street": { "type": "string", "description": "Street of the shipping address.", "example": "Praia de Botafogo" }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address.", "example": "111" }, "neighborhood": { "type": "string", "description": "Neighborhood of the address.", "example": "Botafogo" }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "example": "House", "nullable": true }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "example": "Subway", "nullable": true } } }, "response5": { "type": "object", "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 140.0 }, "description": { "type": "string", "description": "Transaction description.", "example": "GiftCardHub" }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`).", "example": "2023-06-02T18:24:49.252855Z" }, "requestId": { "type": "string", "description": "VTEX request identifier.", "example": "3" }, "settlement": { "type": "object", "description": "Settlement transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL.", "example": "/cosmetics2/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_70/transactions/faa6831230634c4b8fb897e02ba9c5a1/settlements" } } }, "cancellation": { "type": "object", "description": "Cancellation transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL.", "example": "/cosmetics2/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_70/transactions/faa6831230634c4b8fb897e02ba9c5a1/cancellations" } } }, "authorization": { "type": "object", "description": "Authorization transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL.", "example": "/cosmetics2/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_70/transactions/faa6831230634c4b8fb897e02ba9c5a1/authorization" } } }, "operation": { "type": "string", "description": "Operation information (`credit` or `debit`).", "example": "Credit" } } }, "response6": { "type": "object", "required": [ "oid", "value", "date" ], "properties": { "oid": { "type": "string", "description": "Operation identification.", "example": "7cf8d7970e1c81d05620e46cceb6819f" }, "value": { "type": "number", "description": "Value information.", "example": 123.4 }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`).", "example": "2016-01-01T00:00:00" } } }, "response7": { "type": "object", "required": [ "oid", "value", "date" ], "properties": { "oid": { "type": "string", "description": "Operation identification.", "example": "239d35b430fc75379db966c1d3670c6f" }, "value": { "type": "number", "description": "Value information.", "example": 13.4 }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`).", "example": "2016-04-06T00:00:00" } } }, "GiftCardTransactionRequest": { "type": "object", "required": [ "value", "requestId" ], "properties": { "value": { "type": "number", "description": "Value information.", "example": 17.4 }, "requestId": { "type": "string", "description": "VTEX request identifier.", "example": "6360f98eb0cf6fd5afa77e39bba8c20fe5807d8c" } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/authentication-overview#user-token), valid for 24 hours." } } }, "tags": [ { "name": "Gift Card" }, { "name": "Transactions" } ], "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "x-explorer-enabled": true, "x-proxy-enabled": true, "x-samples-enabled": true, "x-samples-languages": ["curl", "node", "ruby", "javascript", "python"] }