Quantity Pricing

Use Price Rules quantity-pricing conditions to offer volume discounts to customers who purchase products in multiple units or large numbers.

To implement quantity pricing with Price Rules, add a rule to your ruleset that includes a quantity-pricing condition.

Price Rules supports these quantity-pricing condition types:

Condition type	Description	Example use case
QTY_BY_VARIANT	Offer discounts based on the quantity of a product variant in the cart.	Buy 3 packages of t-shirts (gray color only) to get a $10.00 discount.
QTY_BY_PRODUCT	Offer discounts based on the number of products in the cart.	Buy 12 cans of pet food (any variety) to get a $10.00 discount.
QTY_BY_LINE	Offer discounts based on the total number of items in the cart.	Buy 10 items to get a $10.00 discount.
BUY_X_GET_Y	Offer discounts on Y items when the cart contains X items.	Buy 3 boxes of tea bags and get a 50% discount on a travel mug.
SPEND_X_GET_Y	Offer discounts on Y items when the cart total is equal to or above X.	A promotion of “Spend $100, get a free bag”.

Using quantity-pricing conditions

Quantity-pricing conditions typically require these properties:

Name	Type	Description
type	string enumeration	The type of quantity-based condition.
value	integer	The quantity of products, product variants, or items that must be present to satisfy the condition.
operator	string	A comparison operator to use when evaluating the condition. Supported operators include =, !=,<, >, <=, and >=.

The following JSON example uses the QTY_BY_LINE type to create a condition that is satisfied when five or more items are present in the cart:

"conditions": [
    {
        "type": "QTY_BY_LINE",
        "value": "5",
        "operator": ">="
    }
]

The exception is the BUY_X_GET_Y condition type, which requires these properties:

Name	Type	Description
type	string enumeration	Use the value BUY_X_GET_Y.
buy_product_selection	object	Defines the subset of products that qualify for the offer.
buy_quantity	integer	The quantity of qualified items the customer must buy to satisfy the condition. The minimum value is 1.
get_quantity	integer	The number of items that get a price adjustment when the customer's cart contains at least buy_quantity number of qualified items. The minimum value is 1.

A BUY_X_GET_Y condition is satisfied when the following is true:

• The customer's cart contains at least buy_quantity items that match the buy_product_selection.
• There are up to get_quanity additional items in the cart that match the parent product_selection.

Conditions that use BUY_X_GET_Y also require that the parent rule includes at least one price adjustment action of the following types: PRICE_ADJUST_PERCENT, PRICE_ADJUST_ABSOLUTE and PRICE_ADJUST_RELATIVE.

The following example condition specifies that when the customer's cart contains at least 1 item with product ID 123, 456, or 789, the customer is eligible for a discount on up to 2 additional items from the parent product_selection:

"conditions": [
  {
    "type": "BUY_X_GET_Y",
    "buy_product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": [
        123,
        456,
        789
      ]
    }
  }
]

The optional uses_per_order_limit property restricts the condition so that the offer can only be applied the specified number of times per cart. In the example above, a customer can buy two qualifying items at regular price and get a price adjustment on up to four additional items, but buying three or more qualifying items does not earn any further discounts.

Creating volume discounts

Combine quantity-pricing conditions with price adjustments to create volume discounts.

To create a volume discount rule, follow this pattern:

1. Add a new rule to your ruleset and set the rule type to one of the discount layers — DISCOUNT or STACKABLE_DISCOUNT. (For more on working with rule types, see Priority and stacking.)
2. Add a quantity pricing condition that defines the volume of products a customer must purchase to qualify for the discount.
3. Add a price adjustment action that defines the discount for qualified purchases.

The following example ruleset offers a promotion to customers who respond to an email campaign — buy 1 item with product ID 123, 456, or 789 and get a 50% discount on 2 items from the parent product_selection:

{
  "ruleset": {
    "product_selection": {
      "type": "PRODUCTS_ALL"
    },
    "rules": [
      {
        "type": "DISCOUNT",
        "conditions": [
          {
            "type": "SOURCE",
            "value": "emailCampaign"
          },
          {
            "type": "BUY_X_GET_Y",
            "buy_product_selection": {
              "type": "PRODUCT_SEARCH",
              "product_ids": [123, 456, 789]
            },
            "buy_quantity": 1,
            "get_quantity": 2,
            "uses_per_order_limit": 2
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_PERCENT",
            "value": -50
          }
        ]
      }
    ]
  }
}

To publish your quantity-pricing promotion, use the Price Rules API to create a ruleset.

For more examples, refer to the other how-to guides in the left-hand menu.

Using SPEND_X_GET_Y

The SPEND_X_GET_Y condition allows you to offer free or discounted items if the cart total is greater or equal to a certain price.

Keep the following considerations in mind when using this condition:

• The price of the item that will be discounted is not considered when determining the price of the cart. For an example of how to use the SPEND_X_GET_Y condition, see quantity-pricing.
• The rule type for this condition must be CART_LEVEL_DISCOUNT.
• The following actions are supported:
  • PRICE_ADJUST_PERCENT
  • PRICE_ADJUST_RELATIVE
  • PRICE_ADJUST_ABSOLUTE
  • PRICE_ADJUST_RELATIVE_WITH_LIMIT
  • PRICE_ADJUST_ABSOLUTE_WITH_LIMIT
• For product selection, always select a product. Never use PRODUCTS_ALL.
• Do not create multiple rules using this condition that select the same product.
• If creating multiple rules using SPEND_X_GET_Y, please note that all valid rules will be applied, not just the one that gives the best price. It is possible for multiple SPEND_X_GET_Y rules to trigger in the same cart.

The following example is a ruleset using SPEND_X_GET_Y, that sets the value of the 111 product to $0 if the cart price is $100 or more.

{
  "ruleset": {
    "internal_name": "Internal Name",
    "external_id": "test",
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": ["111"]
    },
    "rules": [
      {
        "type": "CART_LEVEL_DISCOUNT",
        "conditions": [
          {
            "type": "SPEND_X_GET_Y",
            "operator": ">=",
            "value": 10000
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_ABSOLUTE_WITH_LIMIT",
            "value": 0,
            "limit": 1
          }
        ]
      }
    ]
  }
}

Consider if the product 111 had a regular price of $20. If you added 5 of the product to your cart, this condition would not trigger, because the price of the cart - excluding the 1 product to be discounted - is $80 (4 * $20). Even though overall the cart price is $100, the item that will be discounted is not considered when determining the price of the cart for the SPEND_X_GET_Y condition.

If you had 6 of the product 111 in your cart, then the price of the cart would be $120, and the price of the cart – excluding the item to be discounted – would be $100. Since $100 is over the value specified in the SPEND_X_GET_Y condition, the condition triggers and 1 of the 6 items is be discounted to $0. This results in a line price of $100, with each item individually costing $16.67 (since 6 * 16.67 = 100).