Discount rules

A Discount Rule is an automatic discount. Customers don't type anything: if the cart matches the rule's filters and conditions, the discount applies on its own. Use rules for ongoing promotions ("Buy 2 AirPods, get 1 free"), free-shipping thresholds, tiered pricing, VIP-only deals, time-limited Happy Hours, and bundles.

This page walks through building a rule. For the deep reference, jump to:

• Rule types are the 7 types and the exact config each accepts.
• Conditions are the 15 ways to control when a rule fires.
• Stacking & priority explains how rules and coupons interact.
• Manage discount rules covers editing, enabling, disabling, reprioritizing, translating, and deleting.
• Promotion recipes are ready-made patterns to copy.

Before you start, have the products you want to discount already in your catalog (a rule targets products, categories, tags, or SKUs). If you'll filter by category or tag, set those up first. And if you'll use a time condition (Happy Hour, weekend sale), set your store timezone under Settings → General → Timezone so the rule fires at the right local hour.

Quick steps

1. Go to Marketing → Discount Rules in the sidebar.
2. Click + Add Rule and pick a Type (Product, Order, Buy X Get Y, Volume, Shipping, Bundle…).
3. Set Filters (which products it applies to) and Conditions (when it fires), or leave both empty for an always-on sitewide rule.
4. Set the Discount Config, the actual discount the type applies.
5. Click Create Rule. It's evaluated on every cart within seconds, no code needed.

Two things about step 3 that catch people out on their first rule:

• What the discount comes off is decided by the Type, not by the Method. A Product Discount comes off the filtered items; an Order Discount comes off the whole cart subtotal. That holds for both Percentage and Fixed Amount. With no filters set the two types behave identically, so pick the type that matches what you mean before you add filters.
• On a Shipping Discount, Filters decide which carts qualify. Set Filters = Mattresses and shipping is only discounted on carts that actually contain a mattress. Leave Filters empty and the rule covers every order whose conditions pass.
• A mistyped SKU filter is accepted and matches nothing, forever. SKUs are exact, case-sensitive text and are never checked against your catalog. Categories, Products and Tags are picked from a list and checked when you save.

The detailed walkthrough below covers each step, plus the storefront badges and how to track performance.

Coupons vs Discount Rules

The two can stack, but not by default: a rule only runs alongside a coupon when that rule's Combines with coupons toggle is on, and it is off on every new rule. The coupon side must also allow it (Can combine with other discounts, which is on by default). The Exclusive toggle is about other rules, not coupons, and it does not block a coupon. See Stacking & priority for the full picture.

The 7 rule types at a glance

Every rule has a Type that controls what discount it applies. Pick it first, because the rest of the form changes based on what you choose. You can change it later, but doing so switches the rule off (see Manage discount rules).

Two things about that table are worth knowing before you build anything:

• Product Discount vs Order Discount is the choice of what the discount comes off. A Product Discount is confined to the filtered items; an Order Discount comes off the whole cart subtotal. The Method (Percentage or Fixed Amount) only says how the number is read, never what it applies to. So "$50 off, filtered to Electronics" as a Product Discount takes at most $50 off the electronics and never touches the sofa sitting beside them, while the same thing as an Order Discount takes $50 off the cart total. With no filters set, the two types are identical; the choice only starts to matter once you filter.
• A Shipping Discount respects Filters. Filters decide which carts qualify: with Filters = Mattresses, only a cart containing a mattress gets the shipping saving. Leave Filters empty for every order. You can also gate it with a Condition (Subtotal by Category / Subtotal by Products) when you need a spend threshold rather than mere presence.

→ Full field reference for every type: Rule types.

1. Open the discount rules page

In the sidebar: Marketing → Discount Rules. The list shows every rule with its name, type, status (Active / Disabled), priority, expiry, filters, and conditions.

Each column at a glance:

• Name is the internal label.
• Product Badge Text is what shows up on the product card on your storefront (e.g. "Buy 2 Get 1 Free"). Leave blank if you don't want a badge.
• Type: see the 7 types above.
• Priority: when multiple rules match, lower numbers run first. See Stacking & priority.
• Sales channels are which storefronts the rule applies to (empty = all).
• Banner Text is the sitewide banner the storefront can render at the top of every page. Use for sale announcements.
• Status is Active or Disabled (toggle with one click; no need to delete a rule to pause it).
• Expires is the date the rule auto-deactivates. "No date" = runs forever.
• Filters are which products / categories / tags / SKUs / attributes the rule applies to. On a Shipping Discount the filters shown here decide which carts qualify for the shipping saving; a blank column means every order.
• Conditions set when the rule activates (15 condition types; see Conditions).

2. Add a rule

Click + Add Rule at the top right. The form opens. Pick a Type first because the rest of the form changes based on what you pick.

Common form sections (every type has these)

• Name is your internal label.
• Description holds your notes; not shown to customers.
• Priority: lower runs first. Default 0.
• Enabled: toggle off to save the rule without activating it.
• Sales Channels restrict to specific storefronts; empty = all.
• Start Date / End Date set the validity window.

Filters: which products the rule cares about

The Filters block answers "what do customers have to add to cart for this rule to apply?". Click Edit Filters in the Filters card and a dialog opens where you stack as many filter rows as you need:

Each row is one filter type. The dashboard exposes 4 filter types:

A mistyped SKU is accepted, saves, and matches nothing, forever. The SKU box is free text: whatever you type or paste is compared exactly against each product's or variant's SKU, letter for letter, upper and lower case included. BLK-TEE-M does not match blk-tee-m, and a stray space at the end of a pasted line does not match either. Nothing checks it when you save, nothing flags it later. The rule sits in your list marked Active, showing the SKUs you meant, and quietly discounts nothing. Categories, Products and Tags are different: those are picked from a list and checked when you save, so they cannot be wrong in this way. After building a SKU rule, add one of those SKUs to a test cart and confirm the discount actually appears.

The same applies to an Exclude row of any kind. Exclusions are never checked against your catalog, so a typo in an exclude row excludes nothing and the rule discounts more than you intended, the failure that costs money rather than the one that costs nothing.

Two filter types are API-only and not yet in the dashboard UI: attributes (e.g. material = leather) and brands (e.g. filter to a specific brand). Both follow the same shape, { type: 'attributes' | 'brands', mode: 'include' | 'exclude', values: [...] }, and are set by calling POST /api/discount-rules?storeId=<your store id> with an admin API key (Authorization: Bearer brainerce_*). The storeId query parameter is required; without it the call is rejected. There is no SDK method and no AI-assistant tool for discount rules: a raw HTTP request is the only way to set these two, and the versioned /v1 API does not cover discount rules at all. brands values must be brand IDs; attributes are free text and, like SKUs, are never checked.

Two important controls per row:

• Include / Exclude toggle: "Include" means "apply the rule only to these"; "Exclude" means "apply the rule to everything EXCEPT these". A common pattern: Include Category: Electronics + Exclude Tag: clearance to discount all electronics EXCEPT clearance items.
• × next to each chip removes that value from the row. × next to the row title removes the entire filter row.

Multiple include rows use OR logic: a product qualifies if it matches any of them. The example above ("Charging Accessories" category plus a specific Tag) fires for products in either group, not just those in both. Exclude rows work the other way and always win: anything they match is dropped, no matter how many include rows it satisfied.

To target a true intersection ("in this category and carrying this tag"), use one include row and narrow it with conditions instead.

Leave Filters empty for sitewide, where the rule applies to the whole cart.

Filters work on a Shipping Discount too. They decide which carts qualify: "free shipping when the cart contains a mattress" is built exactly that way, with Type Shipping Discount and Filters = Mattresses, and a cart with no mattress in it pays normal delivery. Leave Filters empty if you mean every order. Use a Condition (Subtotal by Category or Subtotal by Products) instead when the gate is an amount spent rather than an item being present.

What your filters affect depends on the rule's Type. On a Product Discount the discount is confined to the filtered items: a $50 fixed amount filtered to Electronics comes off the electronics, capped at what they are worth. If the filtered items come to less than the fixed amount, the shopper saves only what those items are worth: $50 off filtered to a single $30 phone case pays out $30, and the leftover $20 is not spilled onto the rest of the cart. On an Order Discount the filters decide only whether the rule fires; the discount then comes off the whole cart subtotal. This is true of Percentage and Fixed Amount alike.

Conditions: when the rule activates

Click Edit Conditions on the Conditions card. The dialog starts empty, and no conditions = the rule always fires when filters match.

Click + Add Condition and pick a type from the dropdown. A row appears with three controls: type, operator, and value:

Stack as many rows as you need. The Match toggle at the top decides how rows combine: All conditions must match (AND) or Any condition matches (OR).

→ The full list of all 15 condition types (cart, customer, shipping, time) lives on the Conditions page.

Discount Config: what the rule does

Click into the Discount Config card and a sub-dialog opens with the discount details. For a Product Discount it asks for two things: the Method (Percentage or Fixed Amount) and the Value:

The form is type-aware, and each type asks for different fields. → See Rule types for every field each type accepts, with JSON examples.

Display Config: what the storefront shows

• Banner text is the string for the sitewide banner ("Free shipping over $100!"). Press Enter to split it across two lines, and storefronts render the line break. Stores scaffolded before August 2026 show the break as a space instead; regenerate or update the storefront template to pick it up.
• Badge text is the string for the product-card badge ("Buy 2 Get 1 Free", "BUNDLE"). Always a single line.
• Cart nudge text is the incremental message in the cart ("Add $25 more for free shipping"). Supports placeholders {AMOUNT_NEEDED} and {QUANTITY_NEEDED} so the message updates live as customers add items. Line breaks work here the same way as in the banner text.
• Show on product page / Show in cart / Show as store banner are three toggles that control where each of the strings above actually renders.

Stacking: how the rule interacts with others

• Combines with coupons: toggle on if a customer with a coupon code can ALSO trigger this rule.
• Combines with other rules: toggle on if other rules can run alongside this one.
• Exclusive stops every rule that comes after this one. It does not undo rules that already ran. Under Stack All and Apply First, rules run in Priority order (lowest number first), so a priority-10 rule still applies and then your priority-20 Exclusive rule stacks on top of it. If you want an Exclusive rule to be the only discount on the order, also give it the lowest Priority number in your store (e.g. 0). Under Apply Best an Exclusive rule does win outright, whatever its priority.

Per-rule stacking is overridden by the store-wide Discount Stacking Mode. → Set that up on the Stacking & priority page first; use per-rule toggles only for one-off exceptions.

Usage limits

• Max usage total is total redemptions across all customers.
• Max usage per customer is the cap per customer (typical: 1 for first-order-only).
• Max budget is the cap on total discount $ given out by this rule.

3. Save and the rule is live

Click Create Rule at the bottom of the modal (or Ctrl + Enter). The modal closes and your new rule appears in the list:

Within seconds the rule is evaluated on every cart on your storefront: if a customer adds a smartwatch, the price drops 20% in the cart line and the "20% OFF" badge appears on the product card.

How the storefront shows the discount

Once a rule matches, the storefront does three things automatically:

1. Product card badge. badgeText from Display Config appears on every card that's eligible.
2. Cart line item. The discount appears as its own line in the order summary, with the rule's name as the label.
3. Sitewide banner. If bannerText is set, the storefront top banner shows it on every page.

Multiple discounts on the same order? Each gets its own line in the summary. The customer can see exactly what's saving them what.

One exception: partial shipping discounts. A Shipping Discount set to anything other than Free (or Percentage 100) shows a $0.00 line in the cart. There is no delivery price to take a percentage of until the shopper picks a delivery method, so the saving is applied at the delivery step of checkout instead. The shopper does pay less; the cart just cannot show it yet.

Track how often a rule is used

The rules table has a Usage column showing how many times the rule has been applied, against its total-usage cap. Click that cell and a panel opens where you can edit the caps themselves: max usage total, max usage per customer, and max budget.

That is the whole per-rule reporting surface. Store-wide promotion numbers (active rules, total applications, total discount given, and your top rules) live on the main Dashboard under the Promotions tab.

What does not exist: there is no detail page for a discount rule (clicking a row opens the edit form), no list of the individual orders a rule fired on, no per-rule total-discount figure in the table, and no effectiveness or average-order-value comparison anywhere in the product. If you need per-order attribution, read it from your orders export rather than looking for it here.

What's next?

• Rule types give the exact config for all 7 types.
• Conditions list the 15 condition types in full.
• Stacking & priority covers store-wide modes and "why didn't my rule fire?".
• Promotion recipes are 10 ready-made rule patterns to copy.