API Reference

Getting started

Help us improve our documentation! Tell us about your experience with this article by filling out this form.

The Promotions module is the place where the configuration of promotions and fees applied to your online store is carried out. Here, you can also create coupons to be associated to promotions. According to the configuration, a promotion can be scheduled, enabled or disabled and, after its creation, it can also be found through search or filter tools, and filed.

This overview article goes over what you can accomplish with the VTEX Promotions and Taxes module, including relevant links to our developer documentation about this topic.

Understanding Promotions' module in VTEX

A promotion is a discount granted to the customer. It may be associated with one or more products, with shipping or with a trade policy. At VTEX, the retailer can create a number of rules that, depending on the context of the purchase, will define whether and how the discount will be applied.

In addition, there are six types of promotions:

The coupon is a code entered in the cart by the customer. It grants a discount on the price of the purchase. To make a coupon available for use, you need to associate the coupon to a Promotion. To be valid, the coupon has to be associated with a promotion, and a single coupon can be associated with one or more promotions. But there’s a quantity limit to the active coupons.

Campaign audience is a feature that allows you to define the target audience for promotions, the feature consists of creating criteria for segmenting customers. You can only apply a campaign audience if it is associated with one or more campaign promotions.

Using the Promotions API allows you to manage and retrieve all promotions, coupons and campaign audience from your VTEX store.

Retrieving promotions' information

A VTEX store can have different types of promotions for different kinds of trade policy. To retrieve information about your VTEX store promotions, access the available API.

Managing your promotions

There are several actions a VTEX store can perform on promotions. In the next sections, you will find the main actions related to a store’s promotion management routine.

Updating promotions with multiple SKUs

To update information from a Multiple SKU Promotion.

Archiving/Unarchiving promotions or taxes

If you no longer want a promotion to be used, you can move it to the list of archived promotions or unarchiving if you want to use it. You cannot delete a promotion, only archive it.


Coupons cannot be deleted, only archived. It is important to emphasize that you can only archive one coupon at a time. You can edit and reuse a coupon, but the coupon code can not be modified.

There is a limited quantity of active coupons. Coupon reuse is highly recommended since a high number of coupons may compromise the Promotions & Taxes performance.

If you try to create a coupon with an existing coupon code, the API will update the existing coupon.

Retrieving coupon information

You perform different actions to retrieve coupon information.

Archiving/Unarchiving coupons

You cannot delete coupons, only archive or unarchive them.

Updating coupons

Coupons can be updated as you wish.

Campaign Audiences

To activate the newly created campaign audience, you must associate it to a Campaign promotion.

Creating campaign audiences

You can create campaign audiences to segment your store's promotions based on defining target audiences meeting specific criteria.

Retrieving campaign audience information

You can retrieve campaign audience information using the following APIs.

Policy Engine

The Policy Engine API creates promotion alarms when selling products with undesired prices and promotions. It will create conditions that will check if the prices and the promotions are correct.

If not, the system will alert the store by email with information about the product sold at unexpected prices.

Creating a promotion alert

To create a new promotion alert, you should use this API.

Retrieving policy engine information

You can retrieve policy engine information using the following APIs.

Evaluating policies

Consult and verify all policies that meet the conditions in the request body.

Updating an existing policy

To update an existing promotion alert, you should use this API.

Deleting a policy

To delete an existing promotion alert, you should use this API.


A surcharge is the opposite of a promotion, that is, it is an additional percentage added to the product price in order to increase the value. A surcharge can be configured on the basis of a range of conditions, such as postal code (CEP) range, department, the brand of the products, the customer cluster, and so on. The surcharge is added only in the shopping cart, in the area marked Tax.

The surcharge is applied in accordance with the registration done on the seller. So if your store’s shopping cart has another seller’s product, the surcharge to be applied to that product will be the one registered on the admin of the seller that owns the product. Surcharges registered in the Pricing module will not be taken into account, even if this surcharge is associated with this product.

Retrieving Surcharges/Taxes information

To retrieve information about your VTEX store taxes, access the available API

Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page