The promotion dataset is composed of four tables: promotions_latest, and promotions_historical. These tables cover the entire lifecycle of promotional campaigns.
This section includes the following information:
Data characteristics
| Characteristic | Description |
|---|---|
| Data source | Obtained from the Promotions module in the VTEX Admin. |
| Availability | Promotion data can be accessed through the VTEX Admin and also via the Promotions APIs. |
| History | The data is retained for two years, from 2024 for clients who already use the VTEX platform. |
| Minimum update interval | One hour. |
Table: promotion_latest
| Column name | Column type | Column description |
|---|---|---|
| batch_id | character varying(256) | Unique identifier of the data batch, used to track and manage data ingestion. |
| account | character varying(256) | Account who owns the given promotion. |
| id_calculator_configuration | character varying(256) | The id of the promotion. |
| calculator_name | character varying(65535) | Promotion Name |
| calculator_description | character varying(65535) | Promotion internal description |
| begin_date_utc | timestamp without time zone | Promotion Begin Date (UTC). |
| end_date_utc | timestamp without time zone | Promotion End Date (UTC). |
| last_modified | timestamp without time zone | The last time the promotion was modified (UTC) |
| days_ago_of_purchases | integer | Number of days that are considered to add the purchase history. |
| is_active | boolean | True if the promotion is currently active. |
| is_archived | boolean | True if the promotion is currently archived. |
| is_featured | boolean | True if the promotion is currently featured. |
| disable_deal | boolean | Deprecated Indicates whether a deal is disabled (true) or not (false). |
| offset | numeric(18,0) | The offset to be applied to the promotion's start and end dates. |
| activate_gifts_multiplier | boolean | If set as true, it activates gifts Multiplier. |
| new_offset | numeric(18,0) | New time offset from UTC in seconds. |
| max_prices_per_items | super | List of max price per items. |
| cumulative | boolean | Determines if the promotion can stack with other promotions of the same discount type. |
| effect_type | character varying(256) | The type of the given promotion's effect. |
| discount_type | character varying(256) | The type of discount that will apply to the promotion. |
| nominal_shipping_discount_value | numeric(18,0) | Exact discount to be applied for the shipping value. |
| absolute_shipping_discount_value | numeric(18,0) | Maximum value for the shipping. |
| nominal_discount_value | numeric(18,0) | Exact discount to be applied for the total purchase value. |
| nominal_discount_type | character varying(256) | Controls the behavior of the NominalDiscount effect. This field only accepts two string values:
|
| maximum_unit_price_discount | numeric(18,0) | The maximum price for each item of the purchase will be the price set up. |
| percentual_discount_value | numeric(18,0) | Percentage discount to be applied for total purchase value. |
| rebate_percentual_discount_value | numeric(18,0) | Percentual Shipping Discount Value. |
| percentual_shipping_discount_value | numeric(18,0) | Percentage discount to be applied for shipping value. |
| percentual_tax | numeric(18,0) | Percentual tax over purchase total value. |
| shipping_percentual_tax | numeric(18,0) | Shipping Percentual tax over purchase total value. |
| percentual_discount_value_list1 | numeric(18,0) | Valid discounts for the SKUs in listSku1BuyTogether, discount list used for Buy Together Promotions. |
| percentual_discount_value_list2 | numeric(18,0) | Equivalent to percentualDiscountValueList1. |
| skus_gift | super | SKU Gift Object. Total discount on the product value set as a gift. quantitySelectable Quantity of SKU Gifts. |
Array with SKU Gifts IDs.
| | nominal_reward_value | numeric(18,0) | Nominal value for rewards program. | | percentual_reward_value | numeric(18,0) | Percentage value for rewards program. | | order_status_reward_value | character varying(256) | Order status reward value. | | apply_to_all_shippings | boolean | Specifies whether the promotion applies to all shipping methods or only to the cheapest one. | | nominal_tax | numeric(18,0) | Nominal tax. | | max_pack_value | numeric(18,0) | Maximum pack value | | origin | character varying(256) | Origin of the promotion, marketplace or Fulfillment. | | id_seller_is_inclusive | boolean | 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. | | ids_sales_channel | super | List of Trade Policies that activate this promotion. | | are_sales_channel_ids_exclusive | boolean | 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. | | marketing_tags | super | Promotion Marketing tags. | | marketing_tags_are_not_inclusive | boolean | 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. | | payments_methods | super | Array composed by all the Payments Methods.
- id: Payment Method ID.
- name: Payment Method Name.
- id: Category ID
- name: Category Name
- ⮕ Object containing the ID and Name of the SKU to be added to the first list of the Buy Together promotion.
- Learn more about this type of promotion in the Creating a Buy Together promotion documentation.
- ⮕ Object containing the ID and Name of the SKU to be added to the second list of the Buy Together promotion.
- Learn more about this type of promotion in the Creating a Buy Together promotion documentation.
| | pii_cluster_expressions | super | Cluster expressions related to customers’ personally identifiable information (PII). | | payments_rules | super | List of payment rules | | gift_list_types | super | Gifts List Type | | products_specifications | super | List of product specifications | | affiliates | super | Marketplace order identifier. The discount will apply to selected affiliates. | | max_usage | integer | Defines how many times the promotion can be used. | | max_usage_per_client | integer | Maximum times a customer can use the promotion. | | should_distribute_discount_among_matched_items | boolean | Should distribute discount among matched items | | multiple_use_per_client | boolean | Defines if the promotion can be used multiple times per client | | type | character varying(256) | 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 | boolean | Use progressive algorithm. | | percentual_discount_value_list | super | Percentual discount value list. | | max_number_of_affected_items | integer | The maximum number of affected items for a promotion. | | max_number_of_affected_items_group_key | character varying(256) | The maximum number of affected items by group key for a promotion. |
Table: promotion_historical
| Column name | Column type | Column description |
|---|---|---|
| operation | character varying(256) | The operation executed by the author |
| batch_id | character varying(256) | Unique identifier of the data batch, used to track and manage data ingestion. |
| account | character varying(256) | Account who owns the given promotion. |
| author | character varying(512) | The author of the given operation |
| id_calculator_configuration | character varying(256) | The id of the promotion. |
| calculator_name | character varying(1024) | Promotion Name |
| calculator_description | character varying(65535) | Promotion internal description |
| begin_date_utc | timestamp without time zone | Promotion Begin Date (UTC). |
| end_date_utc | timestamp without time zone | Promotion End Date (UTC). |
| last_modified | timestamp without time zone | The last time the promotion was modified (UTC) |
| days_ago_of_purchases | integer | Number of days that are considered to add the purchase history. |
| is_active | boolean | True if the promotion is currently active. |
| is_archived | boolean | True if the promotion is currently archived. |
| is_featured | boolean | True if the promotion is currently featured. |
| disable_deal | boolean | Deprecated Indicates whether a deal is disabled (true) or not (false). |
| offset | numeric(18,0) | The offset to be applied to the promotion's start and end dates. |
| activate_gifts_multiplier | boolean | If set as true, it activates gifts Multiplier. |
| new_offset | numeric(18,0) | New time offset from UTC in seconds. |
| max_prices_per_items | super | List of max price per items. |
| cumulative | boolean | Determines if the promotion can stack with other promotions of the same discount type. |
| effect_type | character varying(256) | The type of the given promotion's effect. |
| discount_type | character varying(256) | The type of discount that will apply to the promotion. |
| nominal_shipping_discount_value | numeric(18,0) | Exact discount to be applied for the shipping value. |
| absolute_shipping_discount_value | numeric(18,0) | Maximum value for the shipping. |
| nominal_discount_value | numeric(18,0) | Exact discount to be applied for the total purchase value. |
| nominal_discount_type | character varying(256) | Controls the behavior of the NominalDiscount effect. This field only accepts two string
|
| maximum_unit_price_discount | numeric(18,0) | The maximum price for each item of the purchase will be the price set up. |
| percentual_discount_value | numeric(18,0) | Percentage discount to be applied for total purchase value. |
| rebate_percentual_discount_value | numeric(18,0) | Percentual Shipping Discount Value. |
| percentual_shipping_discount_value | numeric(18,0) | Percentage discount to be applied for shipping value. |
| percentual_tax | numeric(18,0) | Percentual tax over purchase total value. |
| shipping_percentual_tax | numeric(18,0) | Shipping Percentual tax over purchase total value. |
| percentual_discount_value_list1 | numeric(18,0) | Valid discounts for the SKUs in listSku1BuyTogether, discount list used for Buy Together Promotions. |
| percentual_discount_value_list2 | numeric(18,0) | Equivalent to percentualDiscountValueList1. |
| skus_gift | super | SKU Gift Object. Total discount on the product value set as a gift.
|
| nominal_reward_value | numeric(18,0) | Nominal value for rewards program. |
| percentual_reward_value | numeric(18,0) | Percentage value for rewards program. |
| order_status_reward_value | character varying(256) | Order status reward value. |
| apply_to_all_shippings | boolean | Specifies whether the promotion applies to all shipping methods or only to the cheapest one. |
| nominal_tax | numeric(18,0) | Nominal tax. |
| max_pack_value | numeric(18,0) | Maximum pack value |
| origin | character varying(256) | Indicates the origin of the promotion, such as 'Marketplace' or 'Fulfillment'. |
| id_seller_is_inclusive | boolean | 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. |
| ids_sales_channel | super | List of Trade Policies that activate this promotion. |
| are_sales_channel_ids_exclusive | boolean | 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. |
| marketing_tags | super | Promotion Marketing tags. |
| marketing_tags_are_not_inclusive | boolean | 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. |
| payments_methods | super | Array composed by all the Payments Methods.
|
| stores | super | List of stores. |
| campaigns | super | Campaign Audiences that activate this promotion. |
| stores_are_inclusive | boolean | Deprecated 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. |
| categories | super | Object composed by the categories that will activate or deactivate the promotion.
|
| categories_are_inclusive | boolean | 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. |
| brands | super | Object composed by the brands that will activate or deactivate the promotion. |
| brands_are_inclusive | boolean | 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. |
| products | super | Object composed by the products that will activate or deactivate the promotion. |
| products_are_inclusive | boolean | 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. |
| skus | super | Object composed by the SKUs that will activate or deactivate the promotion. |
| skus_are_inclusive | boolean | 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. |
| collections1_buy_together | super | Collections that will generate the promotion, type Buy Together, More for less, Progressive Discount, Buy One Get One. |
| collections2_buy_together | super | Collections that will generate the promotion, type Buy Together, More for less, Progressive Discount or Buy One Get One. |
| minimum_quantity_buy_together | integer | Minimum quantity for Buy Together promotion. |
| quantity_to_affect_buy_together | integer | Quantity to affect Buy Together promotion. |
| enable_buy_together_per_sku | boolean | Enable Buy Together per SKU. |
| list_sku1_buy_together | super | Array of objects, each containing ID and Name of an SKU to be added in the first list of the Buy Together promotion. Learn more about this type of promotion in the Creating a Buy Together promotion documentation. ⮕ Object containing the ID and Name of the SKU to be added to the first list of the Buy Together promotion. |
Learn more about this type of promotion in the Creating a Buy Together promotion documentation. | | list_sku2_buy_together | super | Array of objects, each containing ID and Name of an SKU to be added to the second list of the Buy Together promotion. Learn more about this type of promotion in the Creating a Buy Together promotion documentation. ⮕ Object containing the ID and Name of the SKU to be added to the second list of the Buy Together promotion. Learn more about this type of promotion in the Creating a Buy Together promotion documentation.
| | coupon | super | Deprecated List of coupons. | | total_value_floor | numeric(18,0) | Minimum cart value to activate the promotion. | | total_value_ceiling | numeric(18,0) | Maximum chart value to activate the promotion. | | total_value_include_all_items | boolean | Deprecated Total value including all items. | | total_value_mode | character varying(256) | Defines which items are considered for calculating the cart’s total value. | | collections | super | Array composed by the collections that will be activated or deactivated the promotion. | | collections_is_inclusive | boolean | 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. | | restrictions_bins | super | The discount will be granted if the card's BIN is given. | | card_issuers | super | List of card issuers. | | total_value_purchase | numeric(18,0) | Total value a client must have in past orders to active the promotion. | | slas_ids | super | The discount will be granted if the shipping method is the same as the one given. | | is_sla_selected | boolean | Applies selected discount only when one of the defined shipping method is selected by the customer. | | is_first_buy | boolean | Indicates if the promotion is valid only for the user's first purchase. | | first_buy_is_profile_optimistic | boolean | Applies the discount even if the user is not logged. | | compare_list_price_and_price | boolean | If the List Price and Price are the same. | | is_different_list_price_and_price | boolean | Applies the promotion only if the list price and price is different. | | zip_code_ranges | super | Range of the zip code that applies the promotion | | item_max_price | numeric(18,0) | The configuration of the maximum price for an item to activate the promotion. | | item_min_price | numeric(18,0) | The configuration of the minimum price for an item to activate the promotion. | | installment | integer | Deprecated Installment | | is_min_max_installments | boolean | Set if the promotion will be applied considering a minimum and maximum values for installments. | | min_installment | integer | Minimum value for installment. | | max_installment | integer | Maximum value for installment. | | merchants | super | List of merchants. | | cluster_expressions | super | 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. | | pii_cluster_expressions | super | Cluster expressions related to customers’ personally identifiable information (PII). | | payments_rules | super | List of payment rules | | gift_list_types | super | Gifts List Type | | products_specifications | super | List of product specifications | | affiliates | super | Marketplace order identifier. The discount will apply to selected affiliates. | | max_usage | integer | Defines how many times the promotion can be used. | | max_usage_per_client | integer | Maximum times a customer can use the promotion. | | should_distribute_discount_among_matched_items | boolean | Should distribute discount among matched items | | multiple_use_per_client | boolean | Defines if the promotion can be used multiple times per client | | type | character varying(256) | 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 | boolean | Use progressive algorithm. | | percentual_discount_value_list | super | Percentual discount value list. | | max_number_of_affected_items | integer | The maximum number of affected items for a promotion. | | max_number_of_affected_items_group_key | character varying(256) | The maximum number of affected items by group key for a promotion. |
Analyses with promotion data
The promotion dataset can be used for the following analyses:
- Promotion lifecycle analysis: Compare the frequency and duration of promotions to assess the longevity and success of campaigns.
- Promotion reactivation rate: Analyze the number of promotions that are reactivated to determine the effectiveness of reusing or revising previous campaigns.
- Promotion removal trends: Track the number and types of discontinued promotions to understand the removal reasons and adjust future strategies.
- Impact of new promotions: Assess the immediate impact of new promotion launches by comparing them with changes in sales and traffic.
Correlations with other data
The promotion dataset has key relationships with other datasets, some of which are mentioned below:
- Order data: Analyzing the influence of promotions on orders helps to understand their impact on sales.
- Inventory data: Correlating inventory data is important to guarantee the availability of promoted products.
- Marketing and advertising analyses: Integrating this data allows measuring how effective promotions are in attracting traffic and engagement.
- Website navigation data: Analyzing the effect of promotions on navigation provides insights into customer behavior and the effectiveness of promotion display.