Managing a Promotion (hidden)

After promotions are correctly created via Panel or via Admin API, they will have an effect on the customer's Basket and Orders.

Assigning a promotion to a Basket Item

Once a Basket with items are created, the Basket endpoint returns all applicable promotions that can be applied to that basket and to the items that belong to that basket.

To apply a promotion to a specific item, include the promotionId provided in the applicablePromotions in either the Add a Variant call or Update an Item call.

We recommend applying promotions one by one and using the response of the updated basket item (with=applicablePromotions). This ensures there are no conflicts between the promotions.

We would also recommend running this logic generally in two cases:

Upon the first initial load of the basket, to handle new promotions after a user comes back to the shop
After any Basket Action like an Add to Basket or quantity update is done by the use

Understanding Applicable Promotions

The applicable promotions array consists of all promotions that meet the conditions for and can be applied to that item.

Applicable Promotions - In Case Buy X Get Y is Applicable to a Basket Item

Field	Format	Description
itemId	string	The Basket Item ID to which the promotion should be applied. This can be null in case of a `bux_x_get_y` effect where the free item is not in the basket yet.
promotion.id	string	Unique identifier of a promotion
promotion.name	string	The internal name of a promotion
promotion.displayName	string	The name of the promotion that will be displayed to the customers across the order lifecycle
promotion.schedule	object	Set dates which promotion are valid
promotion.isActive	boolean	Identifies if a promotion is active or not
promotion.effect.type	string	`buy_x_get_y`
promotion.effect.additionalData.eligibleItemsQuantity	integer	Defines the quantity amount the customer needs to buy
promotion.effect.additionalData.maxCount	integer	Defines how many items a customer is entitled to get a discount from
promotion.effect.additionalData.maxCountType	string	Max Count Type defines how the quantity amount will be considered to make a promotion eligible for that basket or not. `per_eligible_items_quantity`: in case this option is selected, the total quantity of items in a basket which fulfill the condition of the promotion is considered for the count `per_eligible_uniq_items`: in case this option is selected, the total quantity of unique variant IDs which fulfill the condition of the promotion is considered for the count `per_item_set`: in case this option is selected, the total quantity defined on the Item Set will be used `single_item`: in case this option is selected, the total quantity of unit items within the same variant ID that participate in a promotion is considered for the count
promotion.effect.additionalData.variantIds	Array	Variant IDs which participate in a promotion
promotion.effect.additionalData.discountType	String	Can be `absolute` or `relative`
promotion.effect.additionalData.discountValue	Integer	Discount amount of the promotion in cents
promotion.effect.additionalData.discountDistribution	String	Defines if a discount will be distributed pro_rata or not. In case of a proportional distribution, this value will be reflected as `pro_rata`. Else it will be described as `none`.
promotion.effect.additionalData.applicableItemSelectionType	String	Defines which item in the basket the discount will be applied to. Can be `variant_ids` or `cheapest`.
promotion.conditions	Array of objects	Will describe all conditions that are attached to the promotion
promotion.customData	object	The object with custom fields that are added during promotion creation
promotion.priority	number	The priority of the promotion compared to other promotions. This can be used to decide which promotion to apply if there is a conflict between two
promotion.tiers		Not applicable for Buy X Get Y

Applicable Promotions - In Case Combo Deal is Applicable to a Basket Item

Field	Format	Description
itemId	string	The Basket Item ID to which the promotion should be applied
promotion.id	string	Unique identifier of a promotion
promotion.name	string	The internal name of a promotion
promotion.displayName	string	The name of the promotion that will be displayed to the customers across the order lifecycle
promotion.schedule	object	Set dates which promotion are valid
promotion.isActive	boolean	Identifies if a promotion is active or not
promotion.effect.type	object	`combo_deal`
promotion.effect.additionalData.eligibleItemsQuantity	integer	Defines the quantity amount the customer needs to buy
promotion.effect.additionalData.maxCountType	string	Max Count Type defines how the quantity amount will be considered to make a promotion eligible for that basket or not. `per_eligible_items_quantity`: in case this option is selected, the total quantity of items in a basket which fulfill the condition of the promotion is considered for the count `per_item_set`: in case this option is selected, the total quantity defined on the Item Set will be used `single_item`: in case this option is selected, the total quantity of unit items within the same variant ID that participate in a promotion is considered for the count
promotion.effect.additionalData.price	Integer	Price of the deal in cents
promotion.conditions	Array of objects	Will described all conditions that are attached to the promotion
promotion.customData	object	The object with custom fields that are added during promotion creation
promotion.priority	number	The priority of the promotion compared to other promotions. This can be used to decide which promotion to apply if there is a conflict between two.
promotion.tiers		Not applicable for Combo deals

Applicable Promotions - In Case Automatic Discount is Applicable to a Basket Item

Field	Format	Description
itemId	string	The Basket Item ID to which the promotion should be applied
promotion.id	string	Unique identifier of a promotion
promotion.name	string	The internal name of a promotion
promotion.displayName	string	The name of the promotion that will be displayed to the customers across the order lifecycle
promotion.schedule	object	Set dates which promotion are valid
promotion.isActive	boolean	Identifies if a promotion is active or not
promotion.effect.type	object	`automatic_discount`
promotion.effect.additionalData.type	string	`absolute` or `relative`
promotion.effect.additionalData.value	Integer	Discount amount of the promotion in cents
promotion.conditions	Array of objects	Will described all conditions that are attached to the promotion
promotion.customData	object	The object with custom fields that are added during promotion creation
promotion.priority	number	The priority of the promotion compared to other promotions. This can be used to decide which promotion to apply if there is a conflict between two
promotion.tiers	array of objects	MOV tiers related to the
promotion.tiers.id	number	The identifier of a tier. It is unique for tiers in this promotion
promotion.tiers.mov	number	The minimum order value that would activate a tier in cents
promotion.tiers.name	string	The name of a tier
promotion.tiers.effect.additionalData.type	string	The discount type of a tier. It could be `absolute` or `relative`
promotion.tiers.effect.additionalData.value	number	The discount amount of a tier in cents

Field	Format	Description
promotion.id	string	Unique identifier of a promotion
promotion.name	string	The internal name of a promotion
promotion.version	string	The version of a promotion.
promotion.displayName	string	The name of the promotion that will be displayed to the customers across the order lifecycle
promotion.code	string	The code which was attached to a promotion

Managing list of promotions

Retrieve active promotions with matching ID using GET v1/promotions endpoint.

For details see the Storefront API Reference.

Configuring a promotion on Storefront

For details see the Storefront Configuration Document.