Discount codes and automatic discounts

A discount is one sf_discount record. With a code, the shopper types it in the checkout's Promo Code box. With no code it is automatic: the checkout applies it to every cart that qualifies. The same record runs online and at the till (POS).

A discount is money off (or free shipping, or points) at checkout. A promotion is something else: a sign-up list that hands each subscriber a discount code. For that, see Promotions and the sign-up page.

The checkout never adds up discounts in the browser. It sends the cart and the code to POST storefront/discounts/calculate, and the server answers with the lines, the discounts and the total. That call is how you test a discount too (step 4).

Ask first

• What is the offer? % off, an amount off, buy X get Y, free shipping, or points / store credit given when the order is paid.
• Code or automatic? A code the shopper types (and its text), or applied to every qualifying cart.
• On what? The whole cart, some products, or some categories. Products that must never be discounted.
• Who may use it? Everyone, some customer groups, named customers (by email), first-time customers only.
• Conditions: a minimum spend, a minimum number of items, products that must be in the cart.
• When: start and end date; days of the week or hours of the day.
• How often: total uses, uses per customer.
• Does it combine with other offers running at the same time?

Steps

1. Storefront › Discounts: see what exists

Open Storefront › Discounts (/discount). Tabs: Dashboard, Discounts (?tab=list), Manage. One discount opens with ?openId=<sk>.

call_appengine GET storefront/discounts lists them, highest priority first. It takes status, hasCode (true codes, false automatic), search (name, code, description) and page / pageSize. GET storefront/discounts/stats gives total, active, totalUsage, byStatus, byType. An active discount whose end date has passed counts as expired. GET storefront/discounts/<code or sk> reads one.

Look for an existing offer that already does the job, and for automatic discounts. Those apply to every cart, so a new code may clash with one (see Stacking).

Hands on: the codes in use (a new code must be unique) and any active automatic discounts. Check: the list on screen matches the call.

2. Storefront › Discounts: the discount, as a draft

Create it with call_appengine POST storefront/discounts. Leave status out: a new discount is a draft, which no shopper can use.

{
  "name": "Spring 10",
  "code": "SPRING10",
  "type": "percent",
  "value": 10,
  "applyTo": "cart",
  "minCartValue": 50,
  "endDate": "2026-05-31T23:59:59.000Z",
  "usageLimitPerCustomer": 1
}

It answers with the saved record. The service saves code in capitals and refuses a code that exists already: Discount code SPRING10 already exists. Codes match the shopper's typing without regard to case. Leave code out for an automatic discount.

The offer

The types, as the checkout prices them (all tested):

What it applies to (applyTo):

excludeProducts (SKUs) are never discounted, whatever the scope. The saving is shared out over the covered lines in proportion to their value, and those lines' tax is charged on what is left. On products and categories, a percent or fixed code that covers nothing in the cart is refused (This discount does not apply to the items in your cart).

Who and when

Days and hours are read on the business's clock: the business profile's time zone online, the location's at a till. Without one, UTC.

On screen. Create Discount opens a form with the same fields and a When it applies box for days and hours. It saves through the generic record save, not the call above, so:

• it does not refuse a code that already exists, and it keeps the code as typed. With two records on one code, checkout uses whichever the database returns first. Tested: a second record on an existing 10% code, at 90%, beat the original.
• its Delete removes a discount even after orders used it. DELETE storefront/discounts/<code> refuses that: Cannot delete a discount that has been used.
• freeShippingScope isn't on the form.

So create and delete with the calls; use the screen to read and edit.

Hands on: the discount's code (or, for an automatic one, its sk). Check: GET storefront/discounts/<code> returns it as draft, with the fields as meant. Open it at /discount?tab=list&openId=<sk>.

3. Storefront › Discounts: switch it on

A draft is refused at checkout (This discount is not available yet), so the saving can only be seen once the discount is active.

Stop: an active code works for anyone who has it. An active automatic discount changes the price of every qualifying cart on the live site at once. Show the owner the offer in plain words ("10% off orders over $50, once per customer, until 31 May") and wait for yes.

call_appengine PUT storefront/discounts/<code or sk>/activate. …/deactivate turns it off (inactive). On screen: the row's menu, Activate / Deactivate. Other changes: PUT storefront/discounts/<code or sk> with only the fields to change (code and usageCount are ignored).

Hands on: the active discount. Check: GET storefront/discounts/<code> reads status: "active".

4. Try it with the checkout's own quote

Straight after activating, quote a real basket with the call the checkout makes. If anything is wrong, deactivate at once, fix it and switch it on again. POST storefront/discounts/calculate needs no sign-in on the site's /api, or use call_appengine:

{
  "productItems": [{ "sku": "<SKU>", "quantity": 2 }, { "sku": "<SKU 2>", "quantity": 1 }],
  "couponCode": "spring10",
  "email": "[email protected]",
  "shippingAddress": { "name": "Test", "street1": "1500 Marilla St", "city": "Dallas", "state": "TX", "zip": "75201", "country": "US" }
}

Leave couponCode out to see automatic discounts alone. Prices come from the catalog; never send prices. It answers the whole cart:

Staff pricing for a named customer (to test a group discount): POST storefront/admin/order/quote with the same body plus "customerId": "<customer sk>". It runs the same calculation as that customer. Tested: a guest was refused a group code, a member of the group got it.

Try at least: a basket that qualifies, one just under each minimum, one without the scoped products, and for a group or customer list, a guest and a member.

Check: the first basket's discount and total are what the owner expects, and every refusal reads as the owner would want a shopper to read it. Then, on the site, put the products in the cart, open checkout, type the code in Promo Code and press Apply Coupon. Under Applied Discounts it shows the name, "Code: …" and the saving, and the summary's total matches the quote.

How the checkout applies discounts

In this order, on every quote and again when the order is placed (calculateCart, appengine discount.service.ts 1357–1994):

1. Each line is priced: price lists, quantity tiers, member benefits. A group's benefit % set in Customers & Benefits is part of the price, not a discount record.
2. Automatic discounts, highest priority first. The first money-off one applies; another applies only when it and every one already applied are stackable. Free shipping, deposit, delivery, fee and points discounts always apply.
3. The code (one per order).
4. A staff discount, when staff place an order for a customer.
5. Tax, on each line less its share of the discounts.
6. Shipping. An automatic free shipping is applied inside the shipping quote: the cheapest option (or all, with freeShippingScope: "any") becomes 0, and the checkout charges the cheapest. A free-shipping code takes the whole shipping charge off the total, though productShipping still shows the quoted price (tested: shipping 15, total 50 on a $50 cart).

When the order is placed, each discount it used counts one use (usageCount, and the customer's own count). Codes and automatic discounts both count. A code that a promotion handed out is marked claimed for that subscriber. Cancelling or refunding an order doesn't give the use back.

Stacking: what combines with what

Tested with one automatic 10% on a product and codes on a $50 cart:

What the shopper sees

The checkout shows message under the Promo Code box and in a toast. Branch on reason, not the words.

When it's done

Tell the person:

• the code (or "automatic"), what it gives and on what, in plain words;
• who can use it, when, and how many times;
• the quotes tried: basket, saving, total;
• whether it is on, and what it stacks with.

Open it in Storefront › Discounts (/discount?tab=list&openId=<sk>).

What it can't do yet

• Studio's form allows duplicate codes and deletes used discounts (step 2).
• Online, the better deal doesn't win. An automatic money-off discount always beats a non-stacking code (see Stacking). The "best of the two" code in calculateCart never runs, because automatic discounts are no longer priced into the lines there.
• No coupon box on custom pages. window.appmint.storefront.applyCoupon / calculateDiscounts only quote. The code reaches an order only through the built-in checkout. promotionPrice calls a route that doesn't exist (404).
• The checkout's list of "available promotions" is always empty. It keeps rows marked autoApply, which promotions/active never sends. Only discounts actually applied show.
• Uses aren't given back when an order is cancelled or refunded; POST storefront/discounts/<code>/reverse takes one back by hand. Two online orders finishing together can both take the last use of a usageLimit.
• One code per order.

Don'ts

• Don't switch on an automatic discount without a yes: it changes every qualifying cart at once.
• Don't create or delete discounts on the Studio form when the calls are available; it skips the duplicate and used checks.
• Don't promise that "first order only" or "one per customer" holds for guests; use a customer group for that.
• Don't put a scoped automatic discount and a better non-stacking code side by side and expect the code to win.
• Don't delete a discount orders used; deactivate it.
• Don't send prices in the quote; send SKUs and quantities.