Options & Add-ons

Options and add-ons let customers customize an item at order time: choose toppings, pick a side, add extras, or note preferences — each with its own optional price adjustment. You build an add-on group once (with per-option prices and rules for how many selections are required or allowed) and attach it to any number of items, so a group like “Toppings” or “Gift wrapping” is maintained in one place no matter how many items use it.

Variants vs add-ons — pick the right tool

The catalog has two customization mechanisms; modeling with the right one keeps catalogs and reports clean:

	Variants	Add-ons / options
Customer picks	Exactly one	Zero, one, or many (per your rules)
Typical use	The item’s “axis”: size, color, pack count	Extras layered on top: toppings, sides, gift wrap, preferences
Price effect	Sets the item price	Adds to (or doesn’t change) the price
Example	1L / 2L bottle, S / M / L shirt	Extra cheese +$1, Gift wrap +$3, “No onions”

Rule of thumb: if the item cannot exist without the choice, it’s a variant; if the choice sits on top of the item, it’s an add-on. Variants are covered in the Catalog Builder guide.

Add-on groups

An add-on group is a named set of related options. For each group you decide:

The options inside it — each with a name and a price, which can be zero (“No onions” is free but the kitchen needs to know).
Required or optional — must the customer choose from this group?
How many selections are allowed — single choice (“Choose your sauce”) vs multiple (“Toppings, up to five”).

Attach the group to every item it applies to; because it’s shared, one price fix or new option updates every attached item at once.

Worked examples

Group	Rule	Options
”Choose your sauce”	Required, exactly 1	Garlic aioli · BBQ · Hot honey
”Toppings”	Optional, up to 5	Extra cheese +$1 · Bacon +$1.50
”Gift options”	Optional, up to 1	Gift wrap +$3 · Gift bag +$1.50
”Substitution preference”	Required, exactly 1	Substitute similar · Refund item · Call me (all $0)

Four shapes — forced single choice, capped multi-select, optional upsell, free required preference — cover nearly every vertical. Start with these before inventing exotic rules.

Patterns by vertical

Restaurants — toppings, sauces, cooking preferences, “make it a meal” sides. Required groups prevent kitchen ambiguity (“how spicy?”) better than hoping customers volunteer it.
Retail — gift wrapping, greeting-card text, warranty add-ons, battery inclusion. Mostly optional groups with clear prices.
Supermarkets / grocery — substitution preferences and ripeness/cut preferences work well as zero-price option groups; they capture intent the shopper would otherwise put in a note (or not at all).

How customers experience it

Tapping an item shows its option groups in order; required groups must be completed before the item can be added to the cart, and the price updates live as options are selected. Put required groups first (resolve must-answer questions while attention is highest) and upsell groups last, once the customer is committed to the item. Chosen options travel with the order everywhere: the customer’s receipt, the partner app’s order details, and printed tickets (see Receipt Printing).

Keep groups short and named as instructions — “Choose your sauce (pick 1)” converts better than a vague “Extras” with twenty checkboxes.

Modeling rules that pay off

Never duplicate items to fake options. “Margherita Small” and “Margherita Large” as separate items breaks reporting and search — size is a variant, extras are add-ons.
Order options by popularity — the first options get the most taps.
Use required groups for anything fulfillment must know, not as upsell pressure; forced paid choices read as a dark pattern and hurt trust in your marketplace.
Set marketplace-wide conventions. If your team builds catalogs for merchants during onboarding (see Catalog Builder), standardize group naming and structure so every outlet feels consistent to customers.

Keeping option data healthy

A whole item running out is handled by availability toggles — see Availability. An option-level outage (“no avocado today”) is an edit to the group in the catalog tooling.
Option and group names are translatable like item names — plan translations with the rest of the catalog (Languages & Currencies).
Audit shared groups when prices change: one edit updates everything, if the group was modeled as shared in the first place.
Test like a customer after changes: build the order in the customer app and check the price math and the order details staff will see — required-group mistakes are invisible from the dashboard and obvious from the cart.

Catalog Builder — structure, items, and variants
Availability — stock toggles and outlet hours
Receipt Printing — how options appear on tickets