VTEX Price Tables API

openapi: 3.2.0
info:
  title: VTex Pricing Price Tables API
  description: "Check the new [Pricing onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/pricing-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Pricing and is organized by focusing on the developer's journey.\n\nPricing is the VTEX module responsible for the SKU's price list. In this module, we have the base price of each SKU, optional fixed prices by trade policy, and rules that can be applied to dynamically generate different final prices according to the purchase context and the trade policy. \n\nFind more information on how to use this module and its business logic at our [Pricing onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/pricing-overview).\n\n## Rate limits per route\nThe rate limits per route revolve around the following values:\n\n\n| Operation | Rate | Burst credits  |\n| - | - | - |\n| `GET` | No rate limits | No rate limits |\n| `POST` and `PUT` | 2000 per minute<br>33 per second | 500 |\n| `DELETE` | 1000 per minute<br>16 per second | 300 |\n\n### Burst credits\nIn case the account exceeds the limit frequency for a Rate Limiter (for instance, when one account makes 34 requests per second in any price insert/update route), we decrease from the Burst Credit count the exceeding (in this example, 1 Credit).\n\nIn the event of the Burst Credits reaching 0 (zero), the request is blocked with a Status 429 response.\n\nThe credits fill up over time when the route is not being used, at the same rate as the route's Rate Limiter. In our example, for each second not sending a PUT or POST request, we increase 40 Burst Credits to this Rate Limiter.\n\n### Response Headers for rate limits\nIn the response of any request to the Pricing API, there are headers indicating the current status of the Rate Limiting. This information may be useful to evaluate the ideal frequency to send requests to a route, and when to send a new request in the event of reaching a Rate Limit.\n\n- `Ratelimit-Limit`: Total Burst Credits offered to a route\n- `Ratelimit-Remaining`: How many Burst Credits are still available to use\n- `Ratelimit-Reset`: How long (in seconds) it will take for Burst Credits to fill up completely (it will fill up to the *Ratelimit-Limit*)\n- `Retry-After`: Indicates how many seconds you will need to wait until the Rate Limiter accepts a new request to this route again. If this header response exists, this means your current request has been rate-limited and has not been processed.\n\n\n### Integrating with Pricing v2 considering rate limits\nWhen developing an integration, consider the requests/route/account limits specified in the [Rate Limits per route](#rate-limits-per-route) section, and avoid surpassing this frequency.\n\nIf you happen to be rate limited, please await the time in seconds specified in `Retry-After` before making another request to the service, and reduce the rate of requests per second that your integration is making.\n\n\n\n## Index\n\n### Prices and Fixed Prices\n- `GET` [Get Price](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/prices/-itemId-)\n- `DELETE` [Delete Price](https://developers.vtex.com/docs/api-reference/pricing-api/#delete-/pricing/prices/-itemId-)\n- `PUT` [Create or Update Base Price or Fixed Prices](https://developers.vtex.com/docs/api-reference/pricing-api/#put-/pricing/prices/-itemId-)\n- `GET` [Get Fixed Prices](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/prices/-itemId-/fixed)\n- `POST` [Create or Update Fixed Prices on a price table or trade policy](https://developers.vtex.com/docs/api-reference/pricing-api/#post-/pricing/prices/-itemId-/fixed/-priceTableId-)\n- `GET` [Get Fixed Prices on a price table policy](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/prices/-itemId-/fixed/-priceTableId-)\n- `DELETE` [Delete Fixed Prices on a price table or trade policy](https://developers.vtex.com/docs/api-reference/pricing-api/#delete-/pricing/prices/-itemId-/fixed/-priceTableId-)\n- `GET` [GET Computed Price by price table or trade policy](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/prices/-itemId-/computed/-priceTableId-)\n\n\n### Pricing Configuration\n- `GET` [Get Pricing Configuration](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/config)\n- `GET` [Get Pricing v2 Status](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/migration)\n\n\n### Price Tables\n- `GET` [Get rules for a price table](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/pipeline/catalog/-priceTableId-)\n- `PUT` [Update rules for a price table](https://developers.vtex.com/docs/api-reference/pricing-api/#put-/pricing/pipeline/catalog/-priceTableId-)\n- `GET` [Get all price tables and their rules](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/pipeline/catalog)\n- `GET` [List price tables](https://developers.vtex.com/docs/api-reference/pricing-api/#get-/pricing/tables)\n\n## Common parameters in the documentation\n\n| Parameter name | Description |\n| - | - |\n| `{{accountName}}` | Store account name. |\n| `{{environment}}` | The environment that will be called. |\n| `{{X-VTEX-API-AppKey}}`   | Located in the headers of the requests, user authentication key. |\n| `{{X-VTEX-API-AppToken}}` | Located in the headers of the requests, authentication password. |"
  contact: {}
  version: '1.0'
servers:
- url: https://api.vtex.com/{accountName}
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL
      default: apiexamples
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Price Tables
paths:
  /pricing/pipeline/catalog/{priceTableId}:
    get:
      tags:
      - Price Tables
      summary: VTex Get rules for a price table
      description: 'Retrieves the rules of a specific price table.



        ## Permissions


        Any user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Pricing | Price List | **Read prices** |


        There 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 machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ 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: Getrulesforapricetable
      parameters:
      - name: Content-Type
        in: header
        description: Describes the 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
          example: application/json
      - name: priceTableId
        in: path
        description: Price Table Name.
        required: true
        style: simple
        schema:
          type: string
          example: b2c
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                tradePolicyId: b2c
                rules:
                - id: 0
                  context:
                    categories: {}
                    brands:
                      '2000009': Whiskas
                    stockStatuses: null
                    internalCategories: null
                    markupRange: null
                    dateRange: null
                  percentualModifier: 15
              schema:
                type: object
                properties:
                  tradePolicyId:
                    type: string
                    description: Trade Policy ID (Price Table ID).
                  rules:
                    type: array
                    description: Array of rules for the price table.
                    items:
                      type: object
                      description: Object containing a price table rule.
                      properties:
                        id:
                          type: number
                          description: Rule ID.
                        context:
                          type: object
                          description: Rule Context is a group of filters to be checked at an item level when applying the rule. If all those filters check out, the rule will be applied for that item, unless there is a fixed price for that item.
                          properties:
                            categories:
                              type: object
                              description: 'Categories that an item should have to be eligible for the rule. Format: key: `categoryId`, value: `categoryName`.'
                              additionalProperties:
                                type: string
                                description: Category ID.
                                additionalProperties:
                                  type: string
                                  description: Category Name.
                            brands:
                              type: object
                              description: 'Brands that an item should have to be eligible for the rule. Format: key: `brandId`, value: `brandName`.'
                              additionalProperties:
                                type: string
                                description: Brand ID.
                                additionalProperties:
                                  type: string
                                  description: Brand Name.
                            stockStatuses:
                              type:
                              - object
                              - 'null'
                              description: Stock statuses.
                            internalCategories:
                              type:
                              - object
                              - 'null'
                              description: Internal Categories.
                            markupRange:
                              type:
                              - object
                              - 'null'
                              description: For an item to be eligible to the rule, it's markup should be in this Markup Range.
                              properties:
                                from:
                                  type: integer
                                  description: Item markup should be greater than or equal to this value.
                                to:
                                  type: integer
                                  description: Item markup should be less than or equal to this value.
                            dateRange:
                              type:
                              - object
                              - 'null'
                              description: The rule will be active during this time range.
                              properties:
                                from:
                                  type: string
                                  description: 'Date when rule will be activated. Date format: `RFC3339`.'
                                to:
                                  type: string
                                  description: 'Date when the rule will be deactivated. Date format: `RFC3339`.'
                  percentualModifier:
                    type: integer
                    description: Percentual modifier.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too many requests
      deprecated: false
      servers:
      - url: https://api.vtex.com/{account}/pricing
        variables:
          account:
            default: DefaultParameterValue
    put:
      tags:
      - Price Tables
      summary: VTex Update rules for a price table
      description: 'Updates the rules of a specific price table, by deleting all the rules from the requested price table and creating new rules based on the content of the request.



        ## Permissions


        Any user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Pricing | Price List | **Modify prices** |


        There 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 machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ 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.'
      parameters:
      - name: Content-Type
        in: header
        description: Describes the 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
          example: application/json
      - name: priceTableId
        in: path
        description: Price Table Name.
        required: true
        style: simple
        schema:
          type: string
      responses:
        '201':
          description: Created
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - rules
              example:
                rules:
                - id: 1
                  context:
                    categories:
                      Category ID: '1'
                      Category Name: Alimentação
                    brands:
                      Brand ID: '2000002'
                      Brand Name: Whiskas
                    markupRange:
                      from: 0
                      to: 200
                    dateRange:
                      from: '2022-01-23T19:00:00.000Z'
                      to: '2023-10-26T00:00:00.000Z'
                  percentualModifier: 0
              properties:
                rules:
                  type: array
                  description: Array of rules for the price table.
                  items:
                    type: object
                    description: Object containing a price table rule.
                    required:
                    - id
                    - context
                    - percentualModifier
                    properties:
                      id:
                        type: integer
                        description: Rule ID.
                        example: 0
                      context:
                        type: object
                        description: Rule Context is a group of filters to be checked at an item level when applying the rule. If all those filters check out, the rule will be applied for that item, unless there is a fixed price for that item.
                        required:
                        - categories
                        - brands
                        - markupRange
                        - dateRange
                        properties:
                          categories:
                            type: object
                            description: 'Categories that an item should have to be eligible for the rule. Format: key: `categoryId`, value: `categoryName`.'
                            additionalProperties:
                              type: string
                              description: Category ID.
                              example: '209'
                              additionalProperties:
                                type: string
                                description: Category Name.
                                example: Books
                          brands:
                            type: object
                            description: 'Brands that an item should have to be eligible for the rule. Format: key: `brandId`, value: `brandName`.'
                            additionalProperties:
                              type: string
                              description: Brand ID.
                              example: '421'
                              additionalProperties:
                                type: string
                                description: Brand Name.
                                example: Goldman
                          stockStatuses:
                            type:
                            - object
                            - 'null'
                            description: Stock statuses.
                            example: null
                          internalCategories:
                            type:
                            - object
                            - 'null'
                            description: Internal Categories.
                            example: null
                          markupRange:
                            type:
                            - object
                            - 'null'
                            description: For an item to be eligible to the rule, it's markup should be in this Markup Range.
                            example: null
                            required:
                            - from
                            - to
                            properties:
                              from:
                                type: integer
                                description: Item markup should be greater than or equal to this value.
                                example: 0
                              to:
                                type: integer
                                description: Item markup should be less than or equal to this value.
                                example: 200
                          dateRange:
                            type: object
                            description: The rule will be active during this time range.
                            required:
                            - from
                            - to
                            properties:
                              from:
                                type: string
                                description: 'Date when rule will be activated. Date format: `RFC3339`.'
                                example: '2019-10-23T19:00:00.000Z'
                              to:
                                type: string
                                description: 'Date when the rule will be deactivated. Date format: `RFC3339`.'
                                example: '2019-10-26T00:00:00.000Z'
                      percentualModifier:
                        type: number
                        description: Percentual modifier.
                        example: 0
  /pricing/pipeline/catalog:
    get:
      tags:
      - Price Tables
      summary: VTex Get all price tables and their rules
      description: 'Retrieves a list of all price tables and their rules.



        ## Permissions


        Any user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Pricing | Price List | **Read prices** |


        There 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 machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ 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: getallpricetablesandrules
      parameters:
      - name: Content-Type
        in: header
        description: Describes the 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
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
              - tradePolicyId: '2'
                rules:
                - id: 0
                  context:
                    categories: {}
                    brands: {}
                    stockStatuses: null
                    internalCategories: null
                    markupRange: null
                    dateRange: null
                  percentualModifier: 20
              - tradePolicyId: b2c
                rules:
                - id: 0
                  context:
                    categories: {}
                    brands:
                      '2000009': Whiskas
                    stockStatuses: null
                    internalCategories: null
                    markupRange: null
                    dateRange: null
                  percentualModifier: 15
              schema:
                type: array
                items:
                  type: object
                  description: Information about the price table.
                  properties:
                    tradePolicyId:
                      type: string
                      description: Trade Policy ID (Price Table ID).
                    rules:
                      type: array
                      description: Array of rules for the price table.
                      items:
                        type: object
                        description: Object containing a price table rule.
                        properties:
                          id:
                            type: number
                            description: Rule ID.
                          context:
                            type: object
                            description: Rule Context is a group of filters to be checked at an item level when applying the rule. If all those filters check out, the rule will be applied for that item, unless there is a fixed price for that item.
                            properties:
                              categories:
                                type: object
                                description: 'Categories that an item should have to be eligible for the rule. Format: key: `categoryId`, value: `categoryName`.'
                                additionalProperties:
                                  type: string
                                  description: Category ID.
                                  additionalProperties:
                                    type: string
                                    description: Category Name.
                              brands:
                                type: object
                                description: 'Brands that an item should have to be eligible for the rule. Format: key: `brandId`, value: `brandName`.'
                                additionalProperties:
                                  type: string
                                  description: Brand ID.
                                  additionalProperties:
                                    type: string
                                    description: Brand Name.
                              stockStatuses:
                                type:
                                - object
                                - 'null'
                                description: Stock statuses.
                              internalCategories:
                                type:
                                - object
                                - 'null'
                                description: Internal Categories.
                              markupRange:
                                type:
                                - object
                                - 'null'
                                description: For an item to be eligible to the rule, it's markup should be in this Markup Range.
                                properties:
                                  from:
                                    type: integer
                                    description: Item markup should be greater than or equal to this value.
                                  to:
                                    type: integer
                                    description: Item markup should be less than or equal to this value.
                              dateRange:
                                type:
                                - object
                                - 'null'
                                description: The rule will be active during this time range.
                                properties:
                                  from:
                                    type: string
                                    description: 'Date when rule will be activated. Date format: `RFC3339`.'
                                  to:
                                    type: string
                                    description: 'Date when the rule will be deactivated. Date format: `RFC3339`.'
                    percentualModifier:
                      type: integer
                      description: Percentual modifier.
      deprecated: false
      servers:
      - url: https://api.vtex.com/{account}/pricing
        variables:
          account:
            default: DefaultParameterValue
  /pricing/tables:
    get:
      tags:
      - Price Tables
      summary: VTex List price tables
      description: 'Retrieves a list of all price tables.


        ## Permissions


        Any user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Pricing | Price List | **Read prices** |


        There 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 machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ 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: Listpricetables
      parameters:
      - name: Content-Type
        in: header
        description: Describes the 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
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
              - '1'
              - '2'
              - '3'
              - b2c
              - b2b
              - gold
              schema:
                type: array
                description: Array of price tables.
                items:
                  type: string
                  description: Price table name.
      deprecated: false
      servers:
      - url: https://api.vtex.com/{account}/pricing
        variables:
          account:
            default: DefaultParameterValue
components:
  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.'