Skip to main content
Version: 1.0.0

Promotions Standard Introduction

Promotions Standard offer the flexibility to provide different types of discounts to all your customers or specific customers. You can apply promotions automatically to all purchases, or alternatively, create promotion codes that customers must enter to receive a discount.

You can have multiple promotions active at the same time. Promotions are active in a fixed duration, with defined start and end dates. However, you can manually stop a promotion at any time.

For testing your promotions when scheduling a future date for your shopping cart, you can use the Preview Cart API.

When Creating a Free Gift Promotion, set the promotion to automatic and enable the auto_add_free_gift feature. This way, the shopper will see the free gift in their shopping cart when the target product is added to the cart, and the discount will be applied. This eliminates the need for an additional step to apply the code for the gift discount. However, if you desire more control over when or how the free gift is added, you can choose to use a promotion code and disable the Automatically add free gift items to the cart toggle in Commerce Manager. See Creating Free Gift Promotions. For a seamless process, ensure that the currencies of automatically added gift items match with those of the the items that initiate free gifts. Additionally, ensure that the free gift item is within the same catalog as the eligible items.

For inventory-managed products, ensure that you have sufficient inventory available to run the promotion. If there is insufficient stock of free gift items for all eligible free products, the free gifts won't be added to the cart.

Promotions Standard can be:


The shipping prices do not impact eligibility for item-level and cart-level promotions.

All items in the cart are eligible for cart-level promotions, even if they already have item-level promotions applied. You can select a few products and exclude them from a cart-level promotion. However, the store that uses a simple calculation method does not support promotions with the exclude setting.

Cart-level Promotions

Cart-level promotions are applied to all items in the cart. Cart-level promotions include:

  • Fixed discount: Reduces the cart total by a fixed amount, such as $5.00 off.
  • Percentage discount: Reduces the cart total e by a specific percentage, such as 10% off.

The following image shows a cart before and after applying a 10% Off promotion. With the discount applied, the price for each item is reduced by 10% and the cart total reflects the reduction.

Each item in the cart shows a price that is 10% less than the catalog price.

All items in the cart are eligible for cart-level promotions, even if they already have item-level promotions applied. You can select a few products and exclude them from a cart-level promotion. However, the store that uses a simple calculation method does not support promotions with the exclude setting.

Item-level Promotions

Item-level promotions are applied to each item that qualifies for the promotion. In a shopping cart, the price of each item reflects the discount applied to each item. With the max_applications_per_cart setting, you can limit the number of purchases of an item at the sale price in a cart. For more information, see the Promotions API section.

Item-level promotions include the following promotion types:

  • X for Y: Offers bulk discount based on unit price, such as 2-for-1 sales.

  • X for amount: Offers a bulk discount based on a fixed price, such as 3-for-$20 sales.

  • Bundle: Offers bulk discount when selected products are purchased together. For example, Buy any two items from the list for $100.

  • Item fixed discount: Reduces the price of multiple items by a fixed amount, such as $5.00 off.

  • Percentage item discount: Reduces the product price for multiple items by a specific percentage, such as 10% off. You can also count the number of usages of the promotion per SKU item and limit the usage of the promotion per item. For example, if the usage of the promotion is limited to ten and the shopper purchases two of the same item and three of the another item, five uses of the promotion is deducted from the total usage limit.

  • Free Gift: Offers a free item when a specific product or a group of products are purchased.

    • Item-level promotions are only supported by the line calculation method. For more information about this method, see the Calculation Method section.

    • The max_discount_value setting specifies the maximum possible discount for the cart. To avoid the conflict with the promotions and the promotion to work, we recommend not to use this setting for the following promotions:

      • Cart-level fixed discount
      • Item fixed discount
      • X for Y discount
      • X for amount discount
      • Bundle
      • Free gift
    • The max_applications_per_cart setting, which specifies the maximum number of applications of a promotion per cart, is applicable to line-item promotions only. For example, in a store that offers buy SKU1 get a free gift promotion with maximum application per cart set to one, the buyer can only use the free gift promotion once per cart. If maximum application per cart is not set, the buyer can use the promotion multiple times. You can also set maximum application per cart to zero to remove any usage limit.

    • The exclude array consists of productIDs or SKUs of products to be excluded from the cart-level promotions, such as fixed_discount and percent_discount. However, the stores that use simple calculation method do not support excluding products from promotions.

    • Already existing promotions created before September 28, 2022 will not have created_by and updated_by attributes in their response body.

You can create codes for a promotion so that customers receive the discount only when the code is provided.

Multiple promotions for the same SKU

You can have multiple promotions for the same SKU. However, each instance of the SKU in the cart is eligible for only one item-level promotion.


The promotions are applied in the order of date of creation of the promotions. The oldest promotion is applied first and the newest promotion is applied last. For each instance of a SKU that matches the criteria in the oldest promotion, the promotion is applied. For the remaining instances of the SKU, each instance is compared to the criteria for the next oldest promotion.

For example, a cart consists of 1 BestEver Coffee Maker and 2 BestEver Coffee Grinders. The following promotions are available and applied automatically without a code:

  • An existing BestEver Coffee Maker + Grinder bundle promotion for $200.00. The bundle discount is distributed among the items in the bundle depending on the price of each item.
  • A newly added BestEver Coffee Grinders 10% Off percentage item discount promotion.

In this example, BestEver Coffee Maker costs $150 and BestEver Coffee Grinder costs $100. The promotions works in the following order:

  1. The $50 bundle discount is distributed among the items depending on the cost. In this example, the cost proportion of products is 3:2 and the BestEver Coffee Maker gets $30 discount and BestEver Coffee Grinder gets $20 discount.
  2. The second promotion is applied to the remaining BestEver Coffee Grinders item, and the price is reduced to $90.
  3. The cart total after both discounts is $290 instead of $350.

Understanding how Promotions work with Bundles

Discounting Promotion Bundles

Bundles offer a bulk discount when selected products are purchased together. For example, for a bundle promotion, (SKU1 or SKU2 ) + SKU3, the promotion is applied if the bundle includes either SKU1 and SKU3 or SKU2 and SKU3. This setup encourages the purchase of multiple items together at a discounted rate.

Discounting Product Bundles via promotions

For both Cart-level promotions and Item-level promotions, discounts are applied at the bundle level that can have fixed bundle price or automatic/cumulative pricing.

It is important to note that promotions do not apply to components within a bundle even if the individual item within the components qualifies for promotion. See the following examples:

  • Example 1: Consider that Playtend Games offers a bundle that includes a game console, the Playtend Invaders Game, and the Invaders Controller. If there is an existing Item Percent Discount for the Playtend Invaders Game when sold separately, this discount will not apply when the game is part of the bundle. This ensures that the bundle pricing strategy is maintained.
  • Example 2: In the case of Attribute-based promotions, consider a bundle that consists of Item A with attribute Brand A and Item B with attribute Brand B. If Item A with attribute Brand A qualifies for Item Percent Discount promotion, this discount is not applied to the bundle since the Item A is a component item within the bundle.

To learn how to create a bundle, see Create a Bundle.

Condensed Promotion

A condensed promotion is essentially an object that contains specific meta information about a promotion applied to the cart or order.

Condensed promotions can be retrieved from the following endpoints:

  • Get a Cart: This endpoint displays cart-level condensed promotions within the included object. If ?include=items is specified, the included object also contains cart item-level promotions. The relationships field at the cart level has a promotions section only when ?include=promotions is specified.
  • Get Cart Items: This endpoint shows both cart-level and item-level discounts in a condensed format within the included object.
  • Get an Order: This endpoint displays order-level condensed promotions within the included object.
  • Get Order items: This endpoint displays both order-level and item-level promotions in the included object.

This applies to both Promotions Standard and Rule Promotions.


Security Scheme Type:http
HTTP Authorization Scheme:bearer


Elastic Path: URL: