Modifier groups (add-ons)

A Modifier Group lets a customer customize a product at checkout without creating a new variant for every combination. Think AppleCare+ tiers, engraving, MagSafe case bundles, "first topping free" mechanics. Each modifier adds to the price (or is free), but they don't expand the product catalog the way variants do.

When to use a modifier vs a variant

Rule of thumb: if every choice has its own inventory count, it's a variant. If it just changes price/options without changing what comes out of your warehouse, it's a modifier.

Quick steps

1. In the sidebar: Products → Modifiers.
2. Click + Create modifier group.
3. Fill name, selection rules (Single/Multiple, min/max, free quantity), and add a few modifiers.
4. Click Save Changes, and the group is reusable across many products.
5. Open a product → Modifier Groups field → pick which groups it shows on its checkout.

1. The list view

In the sidebar: Products → Modifier Groups. The list shows every group with its selection rules, modifier count, free policy, and which products use it.

Don't see it in the sidebar? Modifier Groups is a module, and it can be switched off for a store; some store types start with it off. Turn it back on under Settings → Modules.

The columns at a glance:

2. Create a modifier group

Click + Create modifier group. The same modal you'll see when editing one opens up, in two columns: Basic info on the left, Selection rules on the right, and the Modifiers list at the bottom.

To edit an existing group, hover over its row → click the ⋮ menu → Edit. The same form opens pre-filled. Here's what it looks like for the AppleCare+ Coverage group:

Basic info (left column)

• Customer-facing name is shown to shoppers on the storefront. Keep it short ("Box Add-ons", "Engraving").
• Internal name is an admin-only label. Lets you have two groups with the same customer-facing name (e.g. one "Size" for shirts vs another for shoes) without confusion. Never sent to a public storefront API caller.
• Description is customer-facing helper text under the group title at checkout.
• Status: Active shows up on the storefront. Archived hides the group from new product attachments but leaves it on products that already use it.

Selection rules (right column)

• Selection type: Single (radio) for "pick at most one" or Multiple (checkbox) for "pick 0 to max".
• Required, when ON, stops customers checking out without picking from this group. Implies Min ≥ 1.
• Min selections is the floor. 0 = optional, 1+ = required N picks.
• Unlimited maximum, toggled ON, allows as many picks as the customer wants (Max becomes N/A).
• Max selections is the ceiling when unlimited is off.
• Included free sets how many of the customer's picks are at no extra cost. See Free allocation policies for how the discount is distributed.
• Free allocation decides which N picks consume the free slots when the customer exceeds them. See below.

The Modifiers list (bottom)

Each modifier is one option inside the group. Click + to add one, or click the pencil icon on a row to edit. The list scrolls inside the modal.

Each modifier has:

• Name + Description are what the customer sees.
• Price delta is additive to the product price. It can be positive (paid extra), zero (free option), or negative for a downsell, e.g. "Pizza without cheese: -$2.00".
• Image is an optional thumbnail ({ url, thumbnailUrl, alt } JSON). Falls back to a colored monogram avatar if missing.
• SKU is an optional internal SKU for the modifier, useful for reporting.

3. Attach a group to a product

A modifier group is reusable: create it once, attach to as many products as you want. Each product page picks which groups appear on its checkout.

To attach groups:

1. Open the product (Products → ⋮ menu → Edit in Form).
2. In the right-side Organization panel, find the Modifier Groups field.
3. Click the dropdown and pick the groups you want, and they appear as removable chips.
4. The order they appear in is the order the customer sees at checkout.
5. Click Save Changes.

The same group can be attached to dozens of products: edit the group once and every attached product's checkout updates within seconds.

Free allocation policies

When Included free > 0 and a customer's picks exceed that count, the system has to decide which picks count as free and which as paid. The Free allocation dropdown controls that:

Worked example: Box Add-ons (freeQuantity = 1, EXPENSIVE_FREE)

A customer picks 3 add-ons from Box Add-ons:

• MagSafe Case: $29
• Wireless charger: $49
• Extra USB-C cable: $19

With Included free: 1 and policy EXPENSIVE_FREE:

If we'd picked CHEAPEST_FREE instead, the customer would pay $49 + $29 = $78 (the $19 cable goes free). With SELECTION_ORDER, whichever they clicked first is free.

Tip: EXPENSIVE_FREE is almost always the right default, because it maximises perceived value at minimal margin difference vs CHEAPEST_FREE when most carts have a similar mix. Use SELECTION_ORDER only when fairness is the brand story ("first click is on us, no tricks").

Required vs optional patterns

The combination of Selection type, Required, Min, and Max is what makes a group behave the way you want. The 5 common patterns:

Required toggle is just a UX label; under the hood it implies Min ≥ 1. If you set Min: 2 the dashboard auto-enforces the group as required.

Storefront: what customers see

After attaching a group to a product, the storefront renders:

• Single group → radio buttons (or a dropdown if there are many options).
• Multiple group → checkboxes.
• Required group → a red asterisk + the customer can't add to cart until they pick.
• Modifiers with priceDelta > 0 → label shows +$X.XX next to the option.
• Modifiers with priceDelta = 0 → no price shown (it's free).
• Modifiers with priceDelta < 0 → label shows -$X.XX (a downsell, common for "no cheese", "no fries").
• Free quantity mechanics → live calculator. Customer picks 3 add-ons, the cart line item itemizes which is free per the policy.

Groups appear on the product in the order they were attached. The Modifiers field is a multi-select, not a sortable list, so to change the order remove the groups and re-add them in the order you want.

Common patterns

AppleCare+ tier (required choice)

• Selection: Single
• Required: ON, Min 1, Max 1
• Modifiers: No coverage ($0), AppleCare 1yr (+$99), AppleCare+ 2yr (+$199)
• Free policy: (irrelevant, no free quantity)

Engraving (optional one-of-many)

• Selection: Single
• Required: OFF, Min 0, Max 1
• Modifiers: No engraving ($0), Custom text ($0), Emoji or logo (+$5)
• Tip: "No engraving" as the first option makes "skip" frictionless.

Wolt-style toppings (multiple, N free)

• Selection: Multiple
• Min 0, Max 5, Included free 2
• Free allocation: EXPENSIVE_FREE
• Modifiers: Pepperoni (+$3.50), Mushrooms (+$2.50), Olives (+$2.00), Pineapple (+$2.00), Extra cheese (+$3.00)
• Customer picks 3 → priciest 2 free → only pays for the cheapest topping.

Free gift with purchase (fair-game)

• Selection: Multiple
• Min 0, Max 2, Included free 1
• Free allocation: SELECTION_ORDER
• Modifiers: Travel pouch ($9), Cable organizer ($7), Cleaning kit ($5)
• Customer's first click is on us, with no price-gaming and fair to all.

Downsell (negative priceDelta)

• Selection: Single
• Min 0, Max 1
• Modifiers: Standard burger ($0), No cheese (-$2.00), No fries (-$3.00)
• Used in food to handle "make it cheaper by removing".

Architecture notes

A few schema details that matter at scale:

• Modifier.image is JSON { url, thumbnailUrl, alt }. Store a CDN-hosted image and a thumbnail. Missing = colored monogram fallback.
• Modifier.position controls display order inside the group (smallest first). Drag rows in the modal to reorder.
• ProductModifierGroup.position controls order of groups on the product page. Always wins over ModifierGroup.position (which is a default hint for newly-attached products).
• Modifier.priceDelta is Decimal and can be negative, so downsell pricing is supported end-to-end.
• ModifierGroup.translations holds locale-specific names: { "he": { "name": "תוספות", "description": "..." } }. Edit translations via the SDK or the multi-language editor on each modifier group (where supported by your dashboard build).

Marking a modifier sold out

When you run out of an add-on (oat milk, a sauce, a size) you don't need to edit the group. The modifier availability board at /products/sold-out lists every modifier with a toggle, refreshes itself every 30 seconds, and is built to be left open on a screen during service.

Marking one sold out removes it from the customer's choices immediately, everywhere it appears. Toggle it back when you restock.

There is no sidebar entry for this page, so go to /products/sold-out directly and bookmark it.

What's next?

• Variants are for size and color combinations with their own inventory (use variants, NOT modifiers).
• Bulk import attaches modifier groups to many products at once via CSV.
• Discount Rules: Volume and Bundle rules can target products that have modifier groups attached.