Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 55 ยท Shopify Functions

Discount Functions in Depth

Understand Shopify discount functions in depth: product, order and shipping classes, targets, percentage vs fixed values, selection strategies and how discounts combine.

A discount function looks simple: return an operation that says "take this much off". The difficulty is everything around it. Which part of the cart does the discount touch? Is the value a percentage or a fixed amount, and is a fixed amount per item or per group? When two discounts qualify at once, does the customer get both, one, or the better one? Merchants care about those answers more than about your code, because they decide margin.

This lesson covers the three discount classes, the operations and targets for each, the two kinds of value, the selection strategy, and how Shopify decides whether discounts may stack. The real function code and configuration are read-only (they need the CLI and a dev store). The runnable examples are stand-ins in plain JavaScript that model the rules, so you can experiment with numbers. They are simplified, so confirm exact behavior and field names in the current reference for your API version; code here targets 2026-07. If you have not built a function yet, start with Building a Function from Scratch. For the business rules that sit behind any price engine, read Building a Promotions Engine.

The three discount classes

Every app discount declares which classes it can affect. The class tells Shopify where in the order the discount applies and which other discounts it competes with.

Class Affects Operation your function returns
PRODUCT Prices of specific cart lines productDiscountsAdd
ORDER The order subtotal as a whole orderDiscountsAdd
SHIPPING Delivery prices deliveryDiscountsAdd

A single function extension can target more than one class. In current API versions the same function can be registered at a cart target (cart.lines.discounts.generate.run, for product and order discounts) and a delivery target (cart.delivery-options.discounts.generate.run, for shipping discounts). The discount created for it lists its discountClasses, and your code should check that the class it wants to use is enabled, as you saw earlier:

JavaScript
// read-only sketch
export function run(input) {
  const classes = input.discount.discountClasses;
  const operations = [];
  if (classes.includes("PRODUCT")) {
    // maybe push a productDiscountsAdd operation
  }
  if (classes.includes("ORDER")) {
    // maybe push an orderDiscountsAdd operation
  }
  return { operations };
}

When Shopify prices a cart it considers classes in a fixed sequence: product discounts first, then order discounts on what remains, with shipping discounts applied to delivery separately. That is why "10% off an item and 5% off the order" is calculated as two steps rather than 15% off.

flowchart LR
    A["Cart subtotal"] --> B["PRODUCT discounts<br/>(per line)"]
    B --> C["ORDER discounts<br/>(on the remaining subtotal)"]
    A --> D["SHIPPING discounts<br/>(on delivery price)"]
    C --> E["Total to pay"]
    D --> E

Product discounts run first, order discounts apply to what is left, shipping is handled alongside.

Product discounts and targets

A product discount carries a list of candidates. Each candidate has a message, a value and the targets it applies to. For products the target is a cart line, optionally limited to a number of units.

JavaScript
// read-only sketch
{
  productDiscountsAdd: {
    candidates: [
      {
        message: "Mugs: 2 euro off each",
        targets: [{ cartLine: { id: "gid://shopify/CartLine/1" } }],
        value: { fixedAmount: { amount: "2.00", appliesToEachItem: true } },
      },
    ],
    selectionStrategy: "ALL",
  },
}

The id is the cart line id from your input query, not a product id; the line is how Shopify knows quantity and price. Because the cart changes while customers shop, the function runs again on every change, so never cache ids.

Percentage versus fixed amount

There are two kinds of value:

  • Percentage: { percentage: { value: "15" } }. The value is a string, and it is a share of each targeted line's price. It scales with quantity and price automatically.
  • Fixed amount: { fixedAmount: { amount: "5.00" } }. By default the amount is a total to take off across the targets; with appliesToEachItem: true it is taken off every unit of each target line instead.

Choose by intent. "15% off all shoes" is a percentage. "5 off per mug" is a fixed amount applied to each item. "10 off when you buy these three together" is a fixed total across the targets. Money is in the shop's presentment or cart currency as the API defines it for your target, so check which one the input exposes before you compare it with configuration numbers.

Whatever the value, the discount can never push a line below zero. Percentages are a risk only if your configuration is wrong, which is why you validate it (see the previous lesson).

Selection strategy

A product operation can contain several candidates, for example "10% off shoes" and "5 off hats". The selection strategy says what to do with them:

Strategy Meaning
FIRST Apply only the first candidate that is valid. Order your candidates by priority.
ALL Apply every candidate. Use this when the candidates are independent.
MAXIMUM Apply the single candidate that gives the buyer the largest saving.

Order operations use the same idea with a smaller set of strategies (check the reference for the list). The strategy only resolves candidates inside one operation of one discount. How different discounts relate to each other is a separate question.

Order and shipping discounts

An order discount reduces the overall subtotal rather than individual lines. Its target names the subtotal, and it can exclude lines, for example gift cards:

JavaScript
// read-only sketch
{
  orderDiscountsAdd: {
    candidates: [
      {
        message: "5% off orders over 100",
        targets: [{ orderSubtotal: { excludedCartLineIds: [] } }],
        value: { percentage: { value: "5" } },
      },
    ],
    selectionStrategy: "FIRST",
  },
}

A shipping discount is returned by a function that runs at the delivery target and addresses a delivery group:

JavaScript
// read-only sketch
{
  deliveryDiscountsAdd: {
    candidates: [
      {
        message: "Free shipping over 100",
        targets: [{ deliveryGroup: { id: input.cart.deliveryGroups[0].id } }],
        value: { percentage: { value: "100" } },
      },
    ],
    selectionStrategy: "ALL",
  },
}

For delivery you usually want to base eligibility on the cart subtotal. Be careful about which subtotal your input shows: whether it already includes other discounts depends on the target and API version, so check the field description, and decide whether "over 100" means before or after discounts. Promotions logic should state that explicitly; the business side is covered in the promotions-engine lesson linked above.

Combining and stacking

Several discounts can be active in one cart: an automatic volume discount, a customer's code, a free-shipping offer. Whether they stack is decided by the discounts' combination settings, not by your function. When you create the discount you choose which classes it may combine with:

JSON
{
  "discountClasses": ["PRODUCT"],
  "combinesWith": {
    "productDiscounts": false,
    "orderDiscounts": true,
    "shippingDiscounts": true
  }
}

The general rules, simplified:

  1. Two discounts can only apply together if each one allows combining with the other's class. One "no" is enough to block it.
  2. When discounts of the same class cannot combine, Shopify generally keeps the one that is best for the buyer and drops the rest.
  3. Classes are evaluated in the order shown in the diagram, which is why order discounts see a subtotal that product discounts already reduced.

Combination flags are a merchant-facing control, so your admin UI should expose them clearly and explain the consequences. A surprise "my discounts do not stack" is the most common discount support ticket. Limits also exist on how many app discounts can be active at once; check the current numbers before promising unlimited campaigns.

The first stand-in lets you play with candidates, values and strategies on one cart.

JS Percentage, fixed amount and selection strategy

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the last candidate: a fixed amount larger than the targeted lines is capped at their value in the stand-in. Under ALL, overlapping candidates add up in this simple model; in the real platform a line cannot be discounted below zero either, so always test overlapping candidates in a dev store.

The second stand-in is a small discount engine with the class order and the combination rule from above. It applies product discounts first, order discounts on what remains, and shipping separately, and it drops discounts that are not allowed to combine.

JS A discount engine with classes and combination rules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In the big cart, VOLUME10 and MUGS2 are both product discounts, but VOLUME10 does not allow other product discounts, so the lower-value MUGS2 is dropped. In the mid cart the order discount and free shipping both apply because their flags allow it. The ranking by value mirrors the "best for the buyer" rule, but the real service has more cases, so treat this as a thinking tool and verify with real carts.

Design advice for merchants' sake

Keep functions single-purpose: one discount, one rule, a short message that the customer will read at checkout. Prefer several small discounts that merchants can toggle over one giant function with an options screen. Expose the combination flags in your UI with plain-language labels, and show a preview such as "this will not stack with other product discounts". And test the awkward carts: a single item, a zero-priced line, a gift card, a currency with no decimals, and a cart that qualifies for three discounts at once. The testing tools are the subject of Testing and Debugging Functions, and a complete example is built in Project: Tiered Volume Discount.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which operation does a function return to take money off specific cart lines?

    productDiscountsAdd targets cart lines. orderDiscountsAdd reduces the order subtotal and deliveryDiscountsAdd reduces delivery prices.
  2. 2. A fixed-amount value has appliesToEachItem set to true. What does that mean?

    With appliesToEachItem the fixed amount multiplies by quantity. Without it the amount is a total across the targets.
  3. 3. Which selection strategy applies only the candidate that saves the buyer the most?

    MAXIMUM picks the single largest saving. FIRST takes the first valid candidate in your order, and ALL applies every candidate.
  4. 4. Two product discounts qualify, and one of them has productDiscounts set to false in combinesWith. What happens?

    Combination is decided by the discounts' settings, and each side must allow the other's class. When they cannot combine, the better value generally wins.
  5. 5. In what order does Shopify consider the discount classes when pricing a cart?

    That is why an item discount and an order discount multiply their effects in sequence instead of adding percentages.

Summary

  • Discounts belong to classes: PRODUCT (cart lines), ORDER (subtotal) and SHIPPING (delivery); each has its own operation and target type.
  • Values are percentages (strings) or fixed amounts; appliesToEachItem decides whether a fixed amount repeats per unit.
  • The selection strategy (FIRST, ALL, MAXIMUM) resolves candidates inside one operation.
  • Whether different discounts stack is set by the discounts' combination flags; each side must allow the other's class.
  • Classes apply in sequence, so later discounts see a reduced subtotal; check which subtotal your input exposes.
  • Real function code and API calls here are read-only; the engines are simplified stand-ins for experimenting.

Next, learn the other function families that can block or reshape checkout: Cart Validation, Delivery and Payment Customization.