openapi: 3.0.0
info:
  title: VTex 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<table>\n    <tr>\n        <th>Specifications</th>\n        <th>Admin VTEX</th>\n        <th>GiftCard API</th>\n    </tr>\n    <tr>\n        <td><b>Initial value</b></td>\n        <td>You can create gift cards value with any value.</td>\n        <td>All gift cards are generated with no value (balance = 0). After its creation, you need to use <b>Admin VTEX</b> or the <b>Create a gift card transaction</b> to add any balance amount.</td>\n    </tr>\n    <tr>\n        <td><b>Ownership restriction</b></td>\n        <td>You can create gift cards with or without a user assigned to them.</td>\n        <td>All gift cards must be created with a <code>profileId</code> associated to them.</td>\n    </tr>\n    <tr>\n        <td><b>User data identification</b></td>\n        <td>Customer ID (data that identifies a specific client, such as CPF/CNPJ in Brazil).</td>\n        <td><code>profileId</code> (data that identifies a specific client)</td>\n    </tr>\n    <tr>\n        <td><b>Additional Settings</b></td>\n        <td>You can use checkboxes to select whether a gift card will be: <b>Restricted</b> (only a specific customer ID can use this gift card), <b>Reloadable</b> (balance can be changed while it is still active), or <b>Reusable</b> (available for making new purchases with this gift card until its value is completely used up).</td>\n        <td>You can use the following fields to configure the same conditions applied in Admin: <code>restrictedToOwner</code>, <code>multipleCredits</code>, and <code>multipleRedemptions</code>.</td>\n    </tr>\n</table>\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 a gift card](https://developers.vtex.com/docs/api-reference/giftcard-api#post-/giftcards)\r\n- `GET` [Get a gift card by ID](https://developers.vtex.com/docs/api-reference/giftcard-api#get-/giftcards/-giftCardId-)\r\n- `POST` [List all gift cards](https://developers.vtex.com/docs/api-reference/giftcard-api#post-/giftcards/_search)\r\n\r\n### Transaction\r\n\r\n- `POST` [Create a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-api#post-/giftcards/-giftCardId-/transactions)\r\n- `GET` [Get a gift card transaction by ID](https://developers.vtex.com/docs/api-reference/giftcard-api#get-/giftcards/-giftCardId-/transactions/-transactionId-)\r\n- `GET` [List all gift card transactions](https://developers.vtex.com/docs/api-reference/giftcard-api#get-/giftcards/-giftCardId-/transactions)\r\n- `GET` [Get a gift card transaction authorization](https://developers.vtex.com/docs/api-reference/giftcard-api#get-/giftcards/-giftCardId-/transactions/-transactionId-/authorization)\r\n- `POST` [Cancel a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-api#post-/giftcards/-giftCardId-/transactions/-transactionId-/cancellations)\r\n- `GET` [List all gift card transactions cancellations](https://developers.vtex.com/docs/api-reference/giftcard-api#get-/giftcards/-giftCardId-/transactions/-transactionId-/cancellations)\r\n- `POST` [Settle a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-api#post-/giftcards/-giftCardId-/transactions/-transactionId-/settlements)\r\
    \n- `GET` [List all gift card 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: apiexamples
      environment:
        description: Environment to use. Used as part of the URL.
        enum:
          - vtexcommercestable
        default: vtexcommercestable
paths:
  /giftcards:
    post:
      tags:
        - Gift Card
      summary: VTex Create a gift card
      description: "Creates a gift card for a specific user.\r\n\r\n>⚠️ The `redemptionCode` field is auto-generated during gift card creation and cannot be set to an arbitrary value.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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
                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: VTex Get a gift card by ID
      description: "Returns information for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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 identification code used at checkout. Minimum of 6 characters.
                  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 creation 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
                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: VTex List all gift cards
      description: "Returns a list of all gift cards available for a specific customer's cart.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex List all gift card transactions
      description: "Returns the IDs of all transactions performed on a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex Create a gift card transaction
      description: "Creates a transaction (credit or debit) to a gift card and authorize the item reservation.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex Get a gift card transaction by ID
      description: "Returns a specific transaction for a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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
                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: VTex Get a gift card transaction authorization
      description: "Returns information about a gift card transaction authorization.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex List all gift card transactions cancellations
      description: "Returns all transactions cancelled for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex Cancel a gift card 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.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex List all gift card transactions settlements
      description: "Returns all transactions settlements for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: VTex Settle a gift card transaction
      description: "Creates a transaction settlement for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Gift card full access** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      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: Client ID. You can use the customer's registered email or the `userId` parameter which can be found in the [Master Data](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).
          example: 92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff
        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 identification code used at checkout. Minimum of 6 characters.
          example: '***********ASDQ'
        balance:
          type: number
          description: Gift card current balance. For newly created gift cards, the balance will be 0.0.
          example: 0
        relationName:
          type: string
          description: Field to be filled in when it is not necessary to use a loyalty program for the gift card. Note that a new `relationNamevalue` is required for each new gift card to be created.
          example: cardName
        emissionDate:
          type: string
          description: Gift card creation 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: VTEX Loyalty Program
        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. The number described in the URL refers to the gift card identification.
          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:
        redemptionCode:
          type: string
          description: Gift card identification code used at checkout. Minimum of 6 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. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
          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 identification code used at checkout. Minimum of 6 characters.
          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: SKU ID.
          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: michael.scott96@mail.com
        firstName:
          type: string
          description: Customer's first name.
          example: Michael
        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: Defines if the customer is a company (`true`) or not (`false`).
          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: Michael 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
        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. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
              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. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
              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. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
              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/api-authentication-using-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/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'
tags:
  - name: Gift Card
  - name: Transaction
security:
  - appKey: []
    appToken: []
  - VtexIdclientAutCookie: []