Quantity Logic

Configure quantity-based discounts — BOGO offers, per-line caps, item limits, and selection order for the Apply Product Discount block.

Overview

Quantity logic controls how many items receive a discount and which items go first when the cart has more qualifying items than the promotion should cover. Turn it on when you need any of the following:

  • “Buy X, Get Y” promotions — free or discounted gift after a purchase threshold
  • BOGO-style offers — every Nth item discounted
  • Capped promotions — “up to 3 items get 20% off”
  • Cheapest-free / most-expensive-first selection rules
  • Dynamic per-line quantities driven by metafields or bundle builder line properties

Quantity logic is configured inside the Apply Product Discount block. See Basic Discount Settings for the other fields on that block.

Setup

Open the Apply Product Discount block

Select the block in your flow

Toggle Quantity limit

Turn on the Quantity limit switch to reveal the quantity settings

Pick a logic mode

Choose per cart, per cart line, or Match buy group quantity

Enter the quantity

Either a static number or a linked field

Optionally set ordering and an item limit

Control which lines go first and cap the number of distinct lines discounted

Settings

Quantity limit

Optional

Master switch that enables the quantity settings below. When off, the discount applies to every matching item without limits.

Quantity limit logic

Required when Quantity limit is on

Controls how the quantity number is interpreted.

Apply to {qty} items (per cart)

The configured quantity is the total number of units across all matching cart lines. Lines are consumed in the order set by Sort Order until the quantity is exhausted.

Example: Quantity = 5, cart has Item A (qty 3) and Item B (qty 4) — 3 from A and 2 from B are discounted; the remaining 2 units of B stay at full price.

Apply to {qty} items (per cart line)

The quantity applies independently to each matching cart line. Great for “every Nth item” style patterns when used with Sort Order.

Example: Quantity = 2 per cart line, cart has Item A (qty 5) and Item B (qty 3) — 2 units of A and 2 units of B are discounted (4 total).

Match buy group quantity

The discountable quantity is derived from another cart line group — the buy group. This is the “Buy X, Get Y” pattern: customers must buy from group X to unlock discounts on group Y.

Select the buy group in Select buy group below.

Quantity

Required — when logic is per cart or per cart line

The numeric quantity cap. Supports linked fields so the cap can come from a metafield, a cart attribute, or an upstream Count Items / Sum Values block.

Select buy group

Required — when logic is Match buy group quantity

The cart line group that customers must purchase from to unlock the discount. Quantity available for the discount equals the quantity purchased in this group.

Example: Buy group = “Main products” with 2 units → the discount block can apply to 2 units from its Apply to cart line groups (the “get Y” selection on the Apply Product Discount block).

Sort Order

Optional

Determines which items receive the discount first when the quantity isn’t enough to cover everything that matches.

  • Default (no sorting) — cart order, as returned by Shopify
  • Price: Low to High — cheapest items first (good for “free cheapest item” offers)
  • Price: High to Low — most expensive first (good for “save most on premium items” messaging)

Item Limit

Optional

Caps the number of distinct cart lines the discount can touch, regardless of unit quantity. Leave empty for no limit.

Example: Item Limit = 2, cart has three qualifying lines — only the first two (after Sort Order is applied) receive the discount; the third is untouched.

Linked Fields

The Quantity input supports linking — the link icon next to the field swaps the static number for a dynamic source resolved at runtime.

  • Metafield-driven promotions — a promo_quantity metafield on products or the shop sets how many units qualify
  • App-driven bundles — a bundle builder writes the bundle size onto a cart attribute or line property
  • Threshold-based logic — an upstream Count Items block computes how many qualifying items are in the cart and feeds that number into Quantity
  • Tier outputs — a Tiers block picks the cap based on cart subtotal or quantity

Behavior

  • If the linked source doesn’t resolve to a positive number, the matching lines are skipped
  • Values are cast to integers — decimals are truncated
  • The resolved quantity is used by whichever Quantity limit logic mode is active

See Linked Fields in the basic settings reference for the full list of supported sources.

How It Works

Collect matching lines

Take every cart line that belongs to the block’s Apply to cart line groups

Resolve the quantity

Either the static number or the linked source value

Apply sort order

Reorder the matching lines by Sort Order

Consume the quantity

Walk through the sorted lines and discount units until the quantity (and Item Limit, if set) is exhausted

Emit the discount

Shopify receives the discount with the exact subset of lines and units to reduce

Examples

Buy 1, Get 1 Free

Classic BOGO — every second item is free, cheapest first so the cheaper item becomes free.

Discount type

Percentage

Value

100

Quantity limit

On

Logic

Apply to 1 item (per cart line) with Sort Order set to Price: Low to High on pairs — or use Match buy group quantity with a “Buy 1+” group

Message

Buy one, get one free!

Up to 3 Items, 30% Off

Cap the promotion at 3 units across the cart.

Discount type

Percentage with value 30

Quantity limit

On

Logic

Apply to {qty} items (per cart) with Quantity = 3

Sort Order

Price: High to Low (customer saves the most on expensive items)

Buy 2 Shirts, Get 1 Accessory Free

Cross-group “get Y with purchase of X”.

Upstream

Add two Define Cart Line Groups blocks — “Shirts” and “Accessories”

Discount type

Percentage with value 100

Apply to cart line groups

Accessories

Quantity limit

On with Match buy group quantity

Select buy group

Shirts

Message

Free accessory with every 2 shirts!

Metafield-Driven Per-Product Quantity

Each product defines its own promotional quantity via a promo_qty metafield.

Create metafield

Add custom.promo_qty (number_integer) on products

Function input

Include the metafield in the function’s input

Logic

Apply to {qty} items (per cart line)

Quantity

Click the link icon and select custom.promo_qty

Behavior

Each line’s cap comes from its own metafield value; products without the metafield are skipped

Item Limit vs Quantity — What’s the Difference?

These two settings are easy to confuse. They cap different things:

  • Item Limit caps the number of distinct cart lines the discount touches
  • Quantity (per cart or per cart line) caps the number of units discounted

Combined example — Item Limit = 2, Quantity per cart line = 3, cart has three qualifying lines of 5 units each:

  • Line 1 — 3 units discounted (reached per-line quantity cap)
  • Line 2 — 3 units discounted (item-limit slot 2 of 2)
  • Line 3 — NOT discounted (item limit reached)

Troubleshooting

BOGO isn’t applying

  • Need enough items in cart — “every 2nd” requires at least 2 matching units
  • Check cart line group membership on the Apply Product Discount block
  • Confirm Sort Order matches your intent

Wrong items getting discounted

  • Flip Sort Order between Price: Low to High and Price: High to Low
  • Verify the upstream Define Cart Line Groups block is filtering the right products
  • If using linked Quantity, check that the linked source resolves on the expected lines

Discount hits too many or too few units

  • Compare Item Limit vs Quantity — see the table above
  • Multiple discount actions in the same function can interact; check the Discount application strategy on the block
  • Test at exact boundaries (1 unit short, exact amount, 1 unit over)