Promo Module Dataset

5 min

The dataset for the Promo Planner Module is an extension of the Regular Pricing Module dataset, with the following elements:

Promotion Types

Promotion History

Each table indicates the column name in the file, the data type, and a description. Primary keys are highlighted in bold.

Promotion Types

This is a mandatory table, which identifies the types of promotions. The types are meant to be high level classes of campaigns, that define whether the promotions under given type should be taken into account for regular pricing and differentiating targeted promotions from standard ones. Further details of the promotions are captured with the parameters of mechanic (simple discount / multibuy / bundle /..), and marketing attributes (secondary placement in store / front page leaflet /..)

Column	Definition	Example
promo_type_id	Promotion Type identifier, typically corresponding with different promotional strategies and internal processes. For example (1 = Standard Leaflet, 2 = Seasonal Specials, 3 = Targeted Offers)	1
name	Plain text name of the promotion Type	“Standard Leaflet”
regular_pricing_factor	TRUE / FALSE if promotions under this Type should affect regular pricing, for example, preventing regular price change during a set period before a promotion.	TRUE
individually_targeted	TRUE = targeted promotions that only selected customers could apply to, not visible in the stores. FALSE = general promotions either applicable for all, or a broad segment of customers (e.g. loyalty card holders), typically visible in the stores.	FALSE

Promotion History

Actual promotions that were applied (in the ERP/POS). Ideally containing 1 year of history and also including currently running promotions.

Column	Data type	Description
promotion_id	string	Identifier of promotion offer (typically the same ID for multiple products promoted together, e.g. flavors, or all items of a brand in case of an offer like "20% off this brand"). Relates to the historical Sales.
zone_id	string	Pricing zone where the promotion is valid. Use the value -1 if the promotion is valid for all zones.
product_id	string	Product identifier. Relates to the Products table.
valid_from	date	First day of the promotion.
valid_to	date	Last day of the promotion.
promo_type_id	string	Identifier of a Promotion Type. Relates to the definition in Promotion Types table.
promo_mechanic_type	integer	Classification of the promo mechanic into predefined types. Definition with examples further below.
promo_mechanic_value	decimal	Further specification for the mechanic, for example "3" for a multibuy discount that applies when buying 3 units.
promo_price	decimal	Promotional price incl. VAT, see the definition for different special mechanics like X-for-Y. Either promo price or promo discount (amount or percentage) is a mandatory field.
promo_discount_percentage	decimal	Promotional discount in percentages from the regular price applicable to a particular promo mechanics.
promo_discount_amount	decimal	Promotional discount in flat amount from the regular price applicable to a particular promo mechanics.

Optional Columns

Column	Data type	Description
campaign_id	string	Identifier of a group of promotions, typically a single leaflet / particular campaign. Will be available as a filtering option in Promo Analytics.
campaign_name	string	Plain text name of the campaign, e.g. "Leaflet Week 33, 2025"
promotion_name	string	Plain text name of the promotion, e.g. “20% off Coke for loyalty card holders”
regular_price	decimal	Crossed price or otherwise valid price in case the promo was not applied. If not provided, a regular price from sales before the promo is used for evaluation purposes.
regular_cost	decimal	Cost without any deduction from the supplier. Cost from sales before the promotion is used for evaluation if not provided
promo_cost	decimal	Cost applicable for the promo period. Cost from sales transactions is used for evaluation if not provided.
promo_supplier_ rebate_percentage	decimal	%-discount on the cost from the supplier; should not be filled if accounted for in promo_cost.
promo_supplier_funding	decimal	One-time contribution/fee paid by the supplier.
promo_attributes	string	Text containing pipe-delimited attributes that specify marketing or other activities that have an effect on the promo performance. E.g. “Entrance Sign\|Secondary Placement” Historical attributes can significantly improve forecasting accuracy for planned promotions.
segment_ids	string	Customer segment eligibility, e.g. only applicable for loyalty card holders, corresponding to defined Segments. Pipe-delimited if promo applied to multiple segments. NULL if promo applied to all regardless of segments.

Promotion Mechanics Definition

A mapping of the existing promotional approaches to this structure must be performed as a part of the data discovery sessions together with the solution architect.

Please note that this data should only contain promotions defined for a specific set of items. Basket level promotions, customer segment discounts, employee discounts and similar should not be included, since they do not affect the customer behavior when choosing a particular item. They should be only accounted for in Sales transactions as a lower price compared to shelf_price. This data should predominantly contain promotions that were visible in the stores. Targeted promotions such as coupon campaigns shall be included but must be marked with a specific promo_type_id that has a corresponding flag marking it was a targeted campaign in the Promo Types definition.

Mechanic Type	Name	Description	Mechanic Value	Promo Price
1	Standard discount	Simple discount without a condition on the units bought.	NULL	The discounted price
2	Cashback	Promotion of items in the form of a coupon for future purchases or redeemable loyalty points.	NULL	The effective discounted price (full price - cashback)
10	Buy X get 1 free	Conditional promotion when customer buys X+1 units, they pay only for X.	X (1 for 1+1 2 for 2+1 etc.)	The effective discounted price (1+1 = 50% off)
11	Buy X get 1 discounted	Conditional promotion when customer buys X units, they get one discounted.	X (2 in case of a discount like "Buy 2 get 1 at 50% off")	The discounted price
20	Multibuy Tiers	Conditional promotion when customer buys X or more units, they get a lower price. When applied over a group of products with allowed combinations, then all should appear under the same promotion_id (multiple rows).	3 when discount applicable when 3 or more units bought. In case of multiple discounted tiers, multiple rows should appear under the same promotion_id.	The discounted price
21	Multibuy X-for-Y	Conditional promotion when customer buys X units. Also covers the "mix and match", in which case all products should appear under the same promotion_id (multiple rows).	X (3 in case of a discount like "3 for 10")	The effective discounted price of each item
30	Bundle	Conditional promotion when customer buys specifically given combination of products. This should always have at least 2 rows under the same promotion_id.	NULL	The effective discounted price of each item (when bought as a bundle)
40	Spend Threshold	Conditional promotion when customer buys any products for more than set threshold. This should always have at least 2 rows under the same promotion_id. Typically used for multiple products of the same brand.	The threshold (e.g. 30 = spend at least 30 on selected items to apply discount)	The effective discounted price of each item
99	Other	A promotion that does not fit any of the above.	NULL	The discounted price of each item