{ "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.", "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 GiftCard is auto-generated on the creation and cannot be set to an arbitrary value.", "operationId": "CreateGiftCard", "parameters": [ { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "X-VTEX-API-AppKey", "in": "header", "description": "The AppKey configured by the merchant.", "required": true, "style": "simple", "schema": { "type": "string", "default": "{{X-VTEX-API-AppKey}}" } }, { "name": "X-VTEX-API-AppToken", "in": "header", "description": "The AppToken configured by the merchant.", "required": true, "style": "simple", "schema": { "type": "string", "default": "{{X-VTEX-API-AppToken}}" } } ], "requestBody": { "description": "", "content": { "application/vnd.vtex.giftcard.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardRequest" } } }, "required": true }, "responses": { "200": { "description": "", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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", "headers": {}, "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": "Giftcard current balance. For newly created giftcards, the balance will be 0.0." }, "emissionDate": { "type": "string", "description": "Giftcard emission date." }, "expiringDate": { "type": "string", "description": "Giftcard 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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGiftCardusingJSONRequest" }, "example": { "cart": { "grandTotal": 123.1, "relationName": null, "redemptionCode": null, "discounts": 0, "shipping": 0, "taxes": 12, "items": [ { "productId": "1", "id": "1", "refId": "12", "name": "Product Name", "price": 100, "quantity": 1 } ], "itemsTotal": 100 }, "client": { "id": "019a0cc1-409a-4c16-859b-eefdb81f825e", "email": "email@damoain.com", "document": "21301923110" } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionRequest" }, "example": { "operation": "Debit", "value": 3, "description": "GiftCardHub", "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a", "redemptionCode": "", "requestId": "B56CBE231DEE4E1A859183C1030CE926", "orderInfo": { "orderId": "v5006128str", "sequence": 5006128, "cart": { "items": [ { "id": "2001023", "productId": "2000492", "refId": "35994", "name": "Vaporizador Des. ColC4nia Branco", "value": 14.99, "price": 14.99, "quantity": 1, "shippingDiscount": 0, "discount": -7.5, "priceTags": [ { "name": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c", "value": 0 } ] } ], "grandTotal": 0, "discounts": -7.5, "shipping": 7.27, "taxes": 0, "itemsTotal": 14.99 }, "clientProfile": { "profileId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff", "email": "miguel.scott96@yahoo.com.br", "firstName": "miguel", "lastName": "scott", "document": "02906792063", "phone": "+551111111111", "birthDate": "0001-01-01T00:00:00", "isCorporate": false }, "shipping": { "receiverName": "miguel scott", "postalCode": "22250040", "city": "Rio de Janeiro", "state": "RJ", "country": "BRA", "street": "Praia de Botafogo", "number": "111", "neighborhood": "Botafogo", "complement": null, "reference": null } } } } }, "required": false }, "responses": { "200": { "description": "", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GiftCardTransactionRequest" }, "example": { "value": 17.4, "requestId": "6360f98eb0cf6fd5afa77e39bba8c20fe5807d8c" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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", "headers": {}, "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": "Accept", "in": "header", "description": "Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Content-Type", "in": "header", "description": "The Media type of the body of the request. Default value for payment provider protocol is application/json", "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": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GiftCardTransactionRequest" }, "example": { "value": 17.4, "requestId": "6360f98eb0cf6fd5afa77e39bba8c20fe5807d8c" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": {}, "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": { "title": "CreateGiftCardRequest", "required": [ "relationName", "expiringDate", "caption", "profileId" ], "type": "object", "properties": { "relationName": { "type": "string", "description": "Represents the relationship between the client and the store.", "example": "insert example here" }, "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 Giftcard.", "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 Giftcard can only be used for a specified client's ID.", "example": false }, "multipleCredits": { "type": "boolean", "description": "The Giftcard balance can be changed.", "example": false }, "multipleRedemptions": { "type": "boolean", "description": "The Giftcard can be used to make new purchases until its value is completely used.", "example": false } }, "example": { "relationName": "loyalty-program", "expiringDate": "2016-01-01T00:00:00", "caption": "Programa Vtex Fidelidade", "redemptionCode": "BAHD-ASDB-ADQW-ASDQ", "profileId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff", "currencyCode":"USD", "restrictedToOwner": true, "multipleCredits": true, "multipleRedemptions": false } }, "response": { "title": "response", "required": [ "id", "redemptionToken", "redemptionCode", "balance", "relationName", "emissionDate", "expiringDate", "caption", "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": "integer", "description": "Giftcard current balance. For Gift Cards newly created, the balance will be 0.0." }, "relationName": { "type": "string", "description": "Field to be filled in when it is not necessary to use a loyalty program for the GiftCard. Observation: A new `relationNamevalue` is required for each new Giftcard to be created." }, "emissionDate": { "type": "string", "description": "Giftcard emission date." }, "expiringDate": { "type": "string", "description": "Giftcard expiration date." }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the Gift Card." }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "transactions": { "$ref": "#/components/schemas/Transactions" } }, "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" } } }, "Transactions": { "description": "Transactions information.", "required": ["href"], "type": "object", "properties": { "href": { "type": "string", "description": "Giftcard resource URL." } }, "example": { "href": "cards/954/transactions" } }, "GetGiftCardusingJSONRequest": { "required": ["cart", "client"], "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/Cart" }, "client": { "$ref": "#/components/schemas/Client" } }, "example": { "cart": { "grandTotal": 123.1, "relationName": null, "redemptionCode": null, "discounts": 0, "shipping": 0, "taxes": 12, "items": [ { "productId": "1", "id": "1", "refId": "12", "name": "Product Name", "price": 100, "quantity": 1 } ], "itemsTotal": 100 }, "client": { "id": "019a0cc1-409a-4c16-859b-eefdb81f825e", "email": "email@damoain.com", "document": "21301923110" } } }, "Cart": { "title": "Cart information.", "required": [ "grandTotal", "relationName", "redemptionCode", "discounts", "shipping", "taxes", "items", "itemsTotal" ], "type": "object", "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 } }, "default": { "grandTotal": 182, "relationName": null, "redemptionCode": "XTYB", "discounts": 20, "shipping": 2, "taxes": 0, "items": [ { "productId": "2000000", "id": "2000002", "refId": "MEV41", "name": null, "price": 200, "quantity": 1 } ], "itemsTotal": 200 } }, "Item": { "title": "Items information.", "required": [ "productId", "id", "refId", "name", "price", "quantity" ], "type": "object", "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 } }, "default": { "productId": "2000000", "id": "2000002", "refId": "MEV41", "name": "Shoes", "price": 200, "quantity": 1 } }, "Client": { "title": "Customer information.", "required": [ "id", "email", "document" ], "type": "object", "properties": { "id": { "type": "string", "description": "Customer's identification." }, "email": { "type": "string", "description": "Customer's email address." }, "document": { "type": "string", "description": "Document number informed by the customer." } }, "example": { "id": "3b1abc17", "email": "email@domain.com", "document": "234235" } }, "response2": { "title": "response2", "required": ["items", "paging"], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item1" }, "description": "Items information." }, "paging": { "$ref": "#/components/schemas/Paging" } }, "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 } } }, "Item1": { "title": "Item1", "required": ["id", "_self"], "type": "object", "properties": { "id": { "type": "string", "description": "item identification." }, "_self": { "$ref": "#/components/schemas/Self" } }, "example": { "id": "589", "_self": { "href": "cards/589" } } }, "Self": { "required": ["href"], "type": "object", "description": "Object that carries an auto reference of the transaction (on its API).", "properties": { "href": { "type": "string", "description": "Giftcard resource URL." } }, "example": { "href": "cards/589" } }, "Paging": { "title": "Pagination information.", "required": ["page", "perPage", "total", "pages"], "type": "object", "properties": { "page": { "type": "integer", "description": "Page number of the gift card list." }, "perPage": { "type": "integer", "description": "Quantity of gift cards per page." }, "total": { "type": "integer", "description": "Total of gift cards in the store." }, "pages": { "type": "integer", "description": "Total number of pages." } }, "example": { "page": 0, "perPage": 10, "total": 4, "pages": 1 } }, "response3": { "title": "response3", "required": ["id", "_self"], "type": "object", "properties": { "id": { "type": "string", "description": "Transaction identification." }, "_self": { "$ref": "#/components/schemas/Self" } }, "example": { "id": "268", "_self": { "href": "cards/890/transactions/268" } } }, "CreateGiftCardTransactionRequest": { "title": "CreateGiftCardTransactionRequest", "required": [ "operation", "value", "description", "redemptionToken", "redemptionCode", "requestId" ], "type": "object", "properties": { "operation": { "type": "string", "description": "Type of operation. Possible values are: `Debit` or `Credit`." }, "value": { "type": "number", "format": "decimal", "description": "Operation value." }, "description": { "type": "string", "description": "Description information." }, "redemptionToken": { "type": "string", "description": "Gift card redemption token." }, "redemptionCode": { "type": "string", "description": "Gift card redemption code." }, "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 GiftCard balance will not be updated." }, "orderInfo": { "$ref": "#/components/schemas/OrderInfo" } }, "example": { "operation": "Debit", "value": 3, "description": "GiftCardHub", "redemptionToken": "b2dac6f2-f365-48cd-82a9-0b376a55557a", "redemptionCode": "", "requestId": "B56CBE231DEE4E1A859183C1030CE926", "orderInfo": { "orderId": "v5006128str", "sequence": 5006128, "cart": { "items": [ { "id": "2001023", "productId": "2000492", "refId": "35994", "name": "Vaporizador Des. ColC4nia Branco", "value": 14.99, "price": 14.99, "quantity": 1, "shippingDiscount": 0, "discount": -7.5, "priceTags": [ { "name": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c", "value": 0 } ] } ], "grandTotal": 0, "discounts": -7.5, "shipping": 7.27, "taxes": 0, "itemsTotal": 14.99 }, "clientProfile": { "email": "miguel.scott96@yahoo.com.br", "firstName": "miguel", "lastName": "scott", "document": "02906792063", "phone": "+551111111111", "birthDate": "0001-01-01T00:00:00", "isCorporate": false }, "shipping": { "receiverName": "miguel scott", "postalCode": "22250040", "city": "Rio de Janeiro", "state": "RJ", "country": "BRA", "street": "Praia de Botafogo", "number": "111", "neighborhood": "Botafogo", "complement": null, "reference": null } } } }, "OrderInfo": { "description": "Order Information.", "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID." }, "sequence": { "type": "integer", "description": "Sequence number." }, "cart": { "$ref": "#/components/schemas/Cart1" }, "clientProfile": { "$ref": "#/components/schemas/ClientProfile" }, "shipping": { "$ref": "#/components/schemas/Shipping" } }, "default": { "orderId": "v500", "sequence": 5006128, "cart": { "items": [ { "id": "2001023", "productId": "2000492", "refId": "35994", "name": "insert name here", "value": 14.99, "price": 14.99, "quantity": 1, "shippingDiscount": 0, "discount": 2.5, "priceTags": [ { "name": "insert name here", "value": 0 } ] } ], "grandTotal": 0, "discounts": 2.5, "shipping": 7.27, "taxes": 0, "itemsTotal": 14.99 }, "clientProfile": { "email": "email@email.com.br", "firstName": "example", "lastName": "example", "document": "02906792063", "phone": "+551111111111", "birthDate": "0001-01-01T00:00:00", "isCorporate": false }, "shipping": { "receiverName": "example", "postalCode": "22250040", "city": "Rio de Janeiro", "state": "RJ", "country": "BRA", "street": "Praia de Botafogo", "number": "11", "neighborhood": "example", "complement": null, "reference": null } } }, "Cart1": { "description": "Cart information.", "required": [ "items", "grandTotal", "discounts", "shipping", "taxes", "itemsTotal" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item2" }, "description": "Items information." }, "grandTotal": { "type": "integer", "description": "Total payment value." }, "discounts": { "type": "number", "description": "Discounts value." }, "shipping": { "type": "number", "description": "Shipping value." }, "taxes": { "type": "integer", "description": "Taxes value." }, "itemsTotal": { "type": "number", "description": "Total items value." } }, "example": { "items": [ { "id": "2001023", "productId": "2000492", "refId": "35994", "name": "Vaporizador Des. ColC4nia Branco", "value": 14.99, "price": 14.99, "quantity": 1, "shippingDiscount": 0, "discount": -7.5, "priceTags": [ { "name": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c", "value": 0 } ] } ], "grandTotal": 0, "discounts": -7.5, "shipping": 7.27, "taxes": 0, "itemsTotal": 14.99 } }, "Item2": { "description": "Items information.", "required": [ "id", "productId", "refId", "name", "value", "price", "quantity", "shippingDiscount", "discount", "priceTags" ], "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the SKU in VTEX platform." }, "productId": { "type": "string", "description": "Product ID." }, "refId": { "type": "string", "description": "Product Reference ID." }, "name": { "type": "string", "description": "Product name." }, "value": { "type": "number", "description": "Product value." }, "price": { "type": "number", "description": "Product price." }, "quantity": { "type": "integer", "description": "Product quantity." }, "shippingDiscount": { "type": "integer", "description": "Discount to be applied for the shipping value." }, "discount": { "type": "number", "description": "Discount applied on item." }, "priceTags": { "type": "array", "items": { "$ref": "#/components/schemas/PriceTag" }, "description": "" } }, "example": { "id": "2001023", "productId": "2000492", "refId": "35994", "name": "Vaporizador Des. ColC4nia Branco", "value": 14.99, "price": 14.99, "quantity": 1, "shippingDiscount": 0, "discount": -7.5, "priceTags": [ { "name": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c", "value": 0 } ] } }, "PriceTag": { "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.", "required": ["name", "value"], "type": "object", "properties": { "name": { "type": "string", "description": "Price tag name." }, "value": { "type": "integer", "description": "Price tag value." } }, "example": { "name": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c", "value": 0 } }, "ClientProfile": { "description": "Client Profile information.", "required": [ "email", "firstName", "lastName", "document", "phone", "birthDate", "isCorporate" ], "type": "object", "properties": { "email": { "type": "string", "description": "Customer's email address." }, "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "document": { "type": "string", "description": "Document number informed by the customer." }, "phone": { "type": "string", "description": "Customer's phone number." }, "birthDate": { "type": "string", "description": "Customer's birth date." }, "isCorporate": { "type": "boolean", "description": "`true` if the customer is a legal entity." } }, "example": { "email": "miguel.scott96@yahoo.com.br", "firstName": "miguel", "lastName": "scott", "document": "02906792063", "phone": "+551111111111", "birthDate": "0001-01-01T00:00:00", "isCorporate": false } }, "Shipping": { "description": "Shipping information.", "required": [ "receiverName", "postalCode", "city", "state", "country", "street", "number", "neighborhood", "complement", "reference" ], "type": "object", "properties": { "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order." }, "postalCode": { "type": "string", "description": "Postal code." }, "city": { "type": "string", "description": "City of the shipping address." }, "state": { "type": "string", "description": "State of the shipping address." }, "country": { "type": "string", "description": "Country of the shipping address." }, "street": { "type": "string", "description": "Street of the shipping address." }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address." }, "neighborhood": { "type": "string", "description": "Neighborhood of the address." }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "nullable": true }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "nullable": true } }, "example": { "receiverName": "miguel scott", "postalCode": "22250040", "city": "Rio de Janeiro", "state": "RJ", "country": "BRA", "street": "Praia de Botafogo", "number": "111", "neighborhood": "Botafogo", "complement": null, "reference": null } }, "response5": { "title": "response5", "type": "object", "properties": { "value": { "type": "number", "description": "Transaction value." }, "description": { "type": "string", "description": "Transaction description." }, "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`)" }, "requestId": { "type": "string", "description": "VTEX request identifier." }, "settlement": { "type": "object", "description": "Settlement transaction information.", "properties": { "href": { "type": "string", "description": "Giftcard resource URL." } } }, "cancellation": { "type": "object", "description": "Cancellation transaction information.", "properties": { "href": { "type": "string", "description": "Giftcard resource URL." } } }, "authorization": { "type": "object", "description": "Authorization transaction information.", "properties": { "href": { "type": "string", "description": "Giftcard resource URL." } } }, "operation": { "type": "string", "description": "Operation information (`credit` or `debit`)." } }, "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" } }, "response6": { "title": "response6", "required": ["oid", "value", "date"], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "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": { "oid": "7cf8d7970e1c81d05620e46cceb6819f", "value": 123.4, "date": "2016-01-01T00:00:00" } }, "response7": { "title": "response7", "required": ["oid", "value", "date"], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "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": { "id": "239d35b430fc75379db966c1d3670c6f", "value": 13.4, "date": "2016-04-06T00:00:00" } }, "GiftCardTransactionRequest": { "title": "GiftCardTransactionRequest", "required": ["value", "requestId"], "type": "object", "properties": { "value": { "type": "number", "description": "Value information." }, "requestId": { "type": "string", "description": "VTEX request identifier." } }, "example": { "value": 17.4, "requestId": "6360f" } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" } } }, "tags": [ { "name": "Gift Card", "description": "" }, { "name": "Transactions", "description": "" } ], "security": [ { "appKey": [], "appToken": [] } ], "x-explorer-enabled": true, "x-proxy-enabled": true, "x-samples-enabled": true, "x-samples-languages": ["curl", "node", "ruby", "javascript", "python"] }