Get promotion or tax by ID
Retrieves a specific promotion by its Promotion ID or a specific tax by its tax ID.
Permissions
Any user or API key must have at least one of the appropriate License Manager resources 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 |
|---|---|---|
| Rates and Benefits | Manage benefits and rates | GerenciarPromocoesETarifas |
There are no applicable predefined roles for this resource list. You must create a custom 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.
❗ To prevent integrations from having excessive permissions, consider the best practices for managing API keys when assigning License Manager roles to integrations.
Path parameters
Promotion ID or tax ID.
Headers
Type of the content being sent.
HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
Response
OK
Promotion ID.
Promotion Name.
Promotion internal description.
Promotion Begin Date (UTC).
Promotion End Date (UTC).
When the Promotion was last modified.
Number of days that are considered to add the purchase history.
If set as true the Promotion is activated. If set as false the Promotion is deactivated.
If set as true the Promotion is archived. If set as false the Promotion is not archived.
Insert a flag with the promotion name used in the product's window display and page.
Indicates whether a deal is disabled (true) or not (false).
Defines which days of the week the promotion will applied.
Time offset from UTC in seconds.
If set as true, it activates gifts Multiplier.
New time offset from UTC in seconds.
List of max price per items.
Defines if a promotion can accumulate with another one. (true) or not (false).
The type of discount that will apply to the promotion.
Exact discount to be applied for the shipping value.
Maximum value for the shipping.
Exact discount to be applied for the total purchase value.
Controls the behavior of the NominalDiscount effect. This field only accepts two string values:
-item: applies the intended nominal discount on every item present on the cart.
-cart: keeps the behavior as it currently is: the whole order/cart receives a nominal discount that is distributed among the items.
The maximum price for each item of the purchase will be the price set up.
Percentage discount to be applied for total purchase value.
Percentual Shipping Discount Value.
Percentage discount to be applied for shipping value.
Percentual tax over purchase total value.
Shipping Percentual tax over purchase total value.
Valid discounts for the SKUs in listSku1BuyTogether, discount list used for Buy Together Promotions.
Equivalent to percentualDiscountValueList1.
Nominal value for rewards program.
Percentage value for rewards program.
Order status reward value.
The maximum number of affected items for a promotion.
The maximum number of affected items by group key for a promotion.
Promotion will be applied to all kind of shipping.
Nominal tax.
Origin of the promotion, marketplace or Fulfillment. Read Difference between orders with marketplace and fulfillment sources for more information.
Seller Name.
If set to true, this promotion will be applied to any seller present on the idSeller field. If set to false, sellers present on that field will make this promotion not to be applied.
List of Trade Policies that activate this promotion.
If set to false, this promotion will be applied to any trade policies present on the idsSalesChannel field. If set to true, trade policies present on that field will make this promotion not to be applied.
Promotion Marketing tags.
If set to false, this promotion will be applied to any marketing tag present on the marketingTags field. If set to true, marketing tags present on that field will make this promotion not to be applied.
List of stores.
Campaign Audiences that activate this promotion.
Array with conditions IDs.
If set to true, this promotion will be applied to any store present on the stores field. If set to false, stores present on that field will make this promotion not to be applied.
If set to true, this promotion will be applied to any category present on the categories field. If set to false, categories present on that field will make this promotion not to be applied.
If set to true, this promotion will be applied to any brand present on the brands field. If set to false, brands present on that field will make this promotion not to be applied.
If set to true, this promotion will be applied to any product present on the products field. If set to false, products present on that field will make this promotion not to be applied.
If set to true, this promotion will be applied to any SKU present on the skus field. If set to false, SKUs present on that field will make this promotion not to be applied.
Coupon utmSource code.
Coupon utmCampaign code.
Minimum quantity for Buy Together promotion.
Quantity to affect Buy Together promotion.
Enable Buy Together per SKU.
List of coupons.
Minimum chart value to activate the promotion.
Maximum chart value to activate the promotion.
Total value including all items.
If products that already are receiving a promotion, will be considered on the chart total value. There are three options available: IncludeMatchedItems, ExcludeMatchedItems, AllItems.
If set to true, this promotion will be applied to any collection present on the collections field. If set to false, collections present on that field will make this promotion not to be applied.
The discount will be granted if the card's BIN is given.
List of card issuers.
Total value a client must have in past orders to active the promotion.
The discount will be granted if the shipping method is the same as the one given.
Applies selected discount only when one of the defined shipping method is selected by the customer.
Applies the discount only if it's a first buy.
Applies the discount even if the user is not logged.
If the List Price and Price are the same.
Applies the promotion only if the list price and price is different.
List of countries that are activated for this promotion.
Maximum price of the item.
Minimum price of the item.
Installment.
Set if the promotion will be applied considering a minimum and maximum values for installments.
Minimum value for installment.
Maximum value for installment.
List of merchants.
Criteria to select a customer cluster. Each item in this array should follow the format of an equality function ({propertyname}={value}) or the format of a contains function ({propertyname} contains {value}). In both options, {propertyname} must be replaced with the name of the field in the data entity, and {value} must be replaced with the value determined in Master Data. Find more information about these criteria in Filling in the Customer cluster field.
Object composed by a list of SKUs on a Multiple Effects promotion. Structure: "{SkuId}": {PercentageDiscount}. There is a limit of 400 SKUs for this type of promotion.
List of payment rules.
Gifts List Type.
List of product specifications.
Defines how many times the promotion can be used.
Defines if the promotion can be used multiple times per client.
Should distribute discount among matched items.
Defines if the promotion can be used multiple times per client.
Allows the promotion to apply to products whose prices have been manually added by a call center operator.
Defines what is the type of the promotion or indicates if it is a tax. Possible values: regular (Regular Promotion), combo (Buy Together), forThePriceOf (More for Less), progressive (Progressive Discount), buyAndWin (Buy One Get One), maxPricePerItem (Deprecated), campaign (Campaign Promotion), tax (Tax), multipleEffects (Multiple Effects).
Use new progressive algorithm.
Percentual discount value list.