πŸ“£Help us improve our documentation!

Tell us about your experience with this article by filling out

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' architecture in VTEX

For understand Promotions architecture in VTEX, check out the articles below. The rest of this guide focuses on Admin related configurations and actions.

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.

A tax is the opposite of a promotion, that is, it is an additional percentage added to the product price in order to increase the value.

Using the Promotions & Takes API allows you to manage and retrieve all promotions, coupons and tax rules from your VTEX store.

board 2
Retrieving promotions' information

A VTEX store can have different types of promotions and taxes for different kinds of trade policy. To retrieve information about your VTEX store promotions and taxes, 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.

board 2
Creating promotions or taxes

VTEX offers different types of promotions, you can create a promotion or tax, create multiple promotions by SKU and change the settings and data of any promotion using the APIs.

board 2
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.


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.

A single coupon can be associated with one or more promotions. But there’s a quantity limit to the active coupons. We recommend reusing coupons because a high number of coupons can compromise the Promotions & Taxes performance.


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.

board 2
Getting coupons

You can create one coupon or multiple coupons at a time.


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

board 2
Updating coupons

Coupons can be updated as you wish.


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.

Campaign Audiences

Campaign Audience is a feature that allows you to define the target audience for promotions, creating criteria for segmenting customers.

Based on these criteria, the VTEX platform automatically validates whether customers are eligible for a particular campaign audience and, consequently, the associated campaign promotions.

board 2
Creating campaign audiences

Using this API, you can create campaign audiences to segment your store's promotions based on defining target audiences meeting specific criteria.


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

board 2
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 with information about the product sold at unexpected prices.

board 2
Creating a promotion alert

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

board 2
Retrieving policy engine information

You can retrieve policy engine information using the following APIs.

board 2
Updating an existing policy

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

board 2
Deleting a policy

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