vtex.local – Pricing-API

OpenAPI apis-guru

Check the new . 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.

Pricing is the VTEX module responsible for the SKU's price list. At this module we have the base price of each SKU, some optional fixed prices by trade policy, and some rules that can be applied to generate dynamically different final prices according to the purchase context and the trade policy. The variables used in this collection are:

{{accountName}} = You VTEX account name.
{{tradePolicyId}} = Current Trade Policy ID.
{{itemId}} = SKU ID.
{{X-VTEX-API-AppKey}} and {{X-VTEX-API-AppToken}} = Credentials.

You can get more information about how to use this module and its business logic at .

Rate Limits

Limits per route

GET: routes are not rate limited at the moment
PUT or POST: 40 requests/second/account in any price insert/update route with 1000 Burst Credits
DELETE: 16 requests/second/account in any price deletion route, with 300 Burst Credits.

What are Burst Credits?

In case the account exceeds the limit frequency for a Rate Limiter (for instance, when one account makes 41 requests/second in any price insert/update route), we decrease from the Burst Credit count the exceeding (in this example, 1 Credit).

In the event of the Burst Credits reaching 0 (zero), the request is blocked with a Status 429 response.

The credits fill up over time when the route is not being used, in 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

New Response Headers

In the response headers of any request to Pricing v2 there are some new 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.

Ratelimit-Limit - Total Burst Credits offered to a route
Ratelimit-Remaining - How many Burst Credits are still available to use
Ratelimit-Reset - How long (in seconds) it will take to the Burst Credits to fill up completely (It will fill up to the Ratelimit-Limit)
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.

How to integrate with Pricing v2 considering our Rate Limits

Integrate considering the limits of requests/route/account specified in the section, avoiding to surpass this frequency.

If you happen to be Rate Limited, wait 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.

Homepage: https://api.apis.guru/v2/specs/vtex.local:Pricing-API/1.0.json
Provider: vtex.local:Pricing-API / Pricing-API
OpenAPI version: 3.0.0
Spec (JSON): https://api.apis.guru/v2/specs/vtex.local/Pricing-API/1.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/vtex.local/Pricing-API/1.0/openapi.yaml

Tools (16)

Extracted live via the executor SDK.

pricesAndFixedPrices.createorupdatefixedpricesonpricetableortradepolicy
Creates or updates the fixed prices of an SKU for a specific price table or trade policy. You can add one or multiple fixed prices per SKU.
Request body example
json
[ { "value": 50.5, "listPrice": 50.5, "minQuantity": 2, "dateRange": { "from": "2021-12-30T22:00:00-03:00", "to": "2021-12-30T22:00:00-04:00" } }]
```
[  {    "value": 50.5,    "listPrice": 50.5,    "minQuantity": 2,    "dateRange": {      "from": "2021-12-30T22:00:00-03:00",      "to": "2021-12-30T22:00:00-04:00"    }  }]
```
pricesAndFixedPrices.createUpdatePriceOrFixedPrice
Creates or updates an SKU Base Price or Fixed Prices. The base price is the basic selling price of a product, it comprises the cost price and the markup wanted in the sale of the product. The fixed price is an optional price of the SKU for a specific trade policy with a specific minimum quantity to be activated.

You may optionally set a list price. Additionally, you may set either a cost price or a markup value. By defining either one of them, the other will be calculated to conform to the formula costPrice * (1 + markup) = basePrice.

Request body example
json
{ "markup": 30, "basePrice": 100, "listPrice": 35, "fixedPrices": [ { "tradePolicyId": "1", "value": 31, "listPrice": 32, "minQuantity": 1, "dateRange": { "from": "2022-05-21T22:00:00Z", "to": "2023-05-28T22:00:00Z" } }, { "tradePolicyId": "1", "value": 31.5, "listPrice": 33, "minQuantity": 2 } ]}
```
{    "markup": 30,    "basePrice": 100,    "listPrice": 35,    "fixedPrices": [        {            "tradePolicyId": "1",            "value": 31,            "listPrice": 32,            "minQuantity": 1,            "dateRange": {                "from": "2022-05-21T22:00:00Z",                "to": "2023-05-28T22:00:00Z"            }        },        {            "tradePolicyId": "1",            "value": 31.5,            "listPrice": 33,            "minQuantity": 2        }    ]}
```
pricesAndFixedPrices.deletefixedpricesonapricetableortradepolicy

Deletes all Fixed Prices of an SKU in a specific Price Table or Trade Policy.
pricesAndFixedPrices.deletePrice

Deletes the Base Price and all available Fixed Prices for an SKU in all trade policies.
pricesAndFixedPrices.getComputedPricebypricetable
Gets the Computed Price, which is the price after all the steps in the Pricing pipeline, for an SKU in a specific price table or trade policy.
Response body example
json
{ "tradePolicyId": "1", "listPrice": 30, "costPrice": 76.92, "sellingPrice": 18.9, "priceValidUntil": "2018-12-20T18:12:14Z"}
pricesAndFixedPrices.getFixedPrices
The fixed price is an optional price of the SKU for a specific trade policy with a specific minimum quantity to be activated. This method retrieves an array of Fixed Prices for an SKU in a Trade Policy with Minimum Quantities.
The default value for a Minimum Quantity is 1. This means a Fixed Price will be valid for a SKU in a Trade Policy for orders containing the specified number of Minimum Quantity or above, unless a higher Minimum Quantity is specified.
Fixed prices may, optionally, be scheduled. If so, these objects will contain the dateRange object with from and to properties, indicating the start and end time of the scheduled fixed price in the RFC3339 timestamp format (YYYY-MM-DDT23:59:60Z).
Note that the 'Z', at the end, represents the UTC time (GMT+00:00). If it was in GMT-03:00, for example, it would be (YYYY-MM-DDT23:59:60-03:00).
Response body example
json
[ { "tradePolicyId": "6", "value": 20.9, "listPrice": 22.9, "minQuantity": 1, "dateRange": { "from": "2021-12-30T22:00:00-03:00", "to": "2021-12-30T22:00:00-03:00" } }, { "tradePolicyId": "1", "value": 18.9, "listPrice": null, "minQuantity": 1, "dateRange": { "from": "2021-12-30T22:00:00-03:00", "to": "2021-12-30T22:00:00-03:00" } }]
```
[    {        "tradePolicyId": "6",        "value": 20.9,        "listPrice": 22.9,        "minQuantity": 1,        "dateRange": {            "from": "2021-12-30T22:00:00-03:00",            "to": "2021-12-30T22:00:00-03:00"        }    },    {        "tradePolicyId": "1",        "value": 18.9,        "listPrice": null,        "minQuantity": 1,        "dateRange": {            "from": "2021-12-30T22:00:00-03:00",            "to": "2021-12-30T22:00:00-03:00"        }    }]
```
pricesAndFixedPrices.getFixedPricesonapricetable
Retrieves all Fixed Prices on a price table or trade policy.
Response body example
json
[ { "tradePolicyId": "6", "value": 20.9, "listPrice": 22.9, "minQuantity": 1, "dateRange": { "from": "2021-12-30T22:00:00-03:00", "to": "2021-12-30T22:00:00-04:00" } }, { "tradePolicyId": "1", "value": 18.9, "listPrice": null, "minQuantity": 1 }]
```
[    {        "tradePolicyId": "6",        "value": 20.9,        "listPrice": 22.9,        "minQuantity": 1,        "dateRange": {            "from": "2021-12-30T22:00:00-03:00",            "to": "2021-12-30T22:00:00-04:00"        }    },    {        "tradePolicyId": "1",        "value": 18.9,        "listPrice": null,        "minQuantity": 1    }]
```

pricesAndFixedPrices.getPrice

Retrieves price data given a specific SKU ID. Within the fixedPrices object, there might be a list of prices for specific Trade Policies and Minimium Quantities of the SKU. Fixed Prices may also be scheduled.

Response body example

json

{    "itemId": "1",    "listPrice": 50,    "costPrice": 90,    "markup": 30,    "basePrice": 117,    "fixedPrices": [        {            "tradePolicyId": "1",            "value": 50.5,            "listPrice": 50.5,            "minQuantity": 2,            "dateRange": {                "from": "2021-12-31T01:00:00Z",                "to": "2022-12-31T01:00:00Z"            }        },        {            "tradePolicyId": "2",            "value": 30,            "listPrice": 50,            "minQuantity": 2        }    ]}

{    "itemId": "1",    "listPrice": 50,    "costPrice": 90,    "markup": 30,    "basePrice": 117,    "fixedPrices": [        {            "tradePolicyId": "1",            "value": 50.5,            "listPrice": 50.5,            "minQuantity": 2,            "dateRange": {                "from": "2021-12-31T01:00:00Z",                "to": "2022-12-31T01:00:00Z"            }        },        {            "tradePolicyId": "2",            "value": 30,            "listPrice": 50,            "minQuantity": 2        }    ]}

priceTables.getallpricetablesandrules

This method will retrieve all price tables and their rules.

Response body example

json

[    {        "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            }        ]    }]

[    {        "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            }        ]    }]

priceTables.getrulesforapricetable
This method will retrieve the rules from a specific Price Table.
Response body example
json
{ "tradePolicyId": "b2c", "rules": [{ "id": 0, "context": { "categories": {}, "brands": { "2000009": "Whiskas" }, "stockStatuses": null, "internalCategories": null, "markupRange": null, "dateRange": null }, "percentualModifier": 15 }]}
```
{    "tradePolicyId": "b2c",    "rules": [{        "id": 0,        "context": {            "categories": {},            "brands": {                "2000009": "Whiskas"            },            "stockStatuses": null,            "internalCategories": null,            "markupRange": null,            "dateRange": null        },        "percentualModifier": 15    }]}
```
priceTables.listpricetables
This method will list all price tables.
Response body example
json
[ "1", "2", "3", "b2c", "b2b", "gold"]

priceTables.putPricingPipelineCatalogPriceTableId

This method will update the rules from a specific Price Table. It will delete all the rules from the requested Price Table and create new rules based on the content of the request.

Request body example

json

{    "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          }    ]}

{    "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          }    ]}

pricingConfiguration.getPricingConfig

Retrieves Pricing Configuration.

Response body example

json

{    "hasMigrated": true,    "migrationStatus": "Completed",    "defaultMarkup": 100,    "priceVariation": {        "upperLimit": null,        "lowerLimit": null    },    "minimumMarkups": {        "1": 100,        "2": 90    },    "tradePolicyConfigs": [],    "sellersToOverride": [],    "hasPriceInheritance": false,    "priceInheritance": "never",    "hasOptionalBasePrice": false,    "blockAccount": false,    "blockedRoutes": null,    "priceTableSelectionStrategy": "first",    "priceTableLimit": null}

{    "hasMigrated": true,    "migrationStatus": "Completed",    "defaultMarkup": 100,    "priceVariation": {        "upperLimit": null,        "lowerLimit": null    },    "minimumMarkups": {        "1": 100,        "2": 90    },    "tradePolicyConfigs": [],    "sellersToOverride": [],    "hasPriceInheritance": false,    "priceInheritance": "never",    "hasOptionalBasePrice": false,    "blockAccount": false,    "blockedRoutes": null,    "priceTableSelectionStrategy": "first",    "priceTableLimit": null}

pricingConfiguration.getPricingv2Status
Retrieves Pricing v2 Status.
Response body example
json
{ "isActive": true, "hasMigrated": true}
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools