Promo codes
One code per order, a percentage or a fixed amount, with limits on validity, total use and use per buyer. Managed in the Promo codes grid.
What a code can be
| Field | What it does |
|---|---|
code | what the buyer types. Unique across the shop |
type | percent or fixed |
percent | the percentage, 0–100, for percent |
discounts | the amount per currency, for fixed |
currencies | which currencies it works in. Empty means all |
min_amount | the minimum goods total, per currency |
starts_at / ends_at | validity. Empty at either end means open-ended |
usage_limit | how many times in total |
usage_limit_per_user | how many times per buyer |
used | the counter, for reading |
published_at | an unpublished code does not work |
A fixed discount is per currency rather than one number converted at a rate, for the same reason prices are — see Currencies. A code with no amount for the buyer's currency does not apply, rather than applying a converted guess.
Why the amount is per currency and not converted
"500 off" converted from roubles becomes "€5.43 off". Nobody advertises that. A discount is a round number in the currency it is offered in, which means naming it in each.
How the discount is computed
On the goods only, never on delivery. A percentage is floor-divided in minor units, so there are no half-cent discounts and no floating-point drift: 33% of one cent is zero, not 0.33.
The discount is capped at the goods total. A €50 fixed code on a €30 order discounts €30, not €50 — a promo code is not a way to get money out of the shop.
The result is a snapshot on the order and a line in the invoice. The buyer sees it as a line above the total.
Where the code lives
In the cart, not in the checkout form, so it survives a page reload: /pay/cart/promo stores it, and an empty code removes it. Checkout picks it up from there by itself when a cart is being ordered.
The promocode field on the checkout request stays for one-step purchase that bypasses the cart, and there it wins over whatever is stored.
A stored code is re-checked on every view of the cart, because it may have expired or run out since. If it has, the cart says so rather than quietly dropping the discount.
Counting
The counter is a column on the code, incremented on order creation — and incremented conditionally, in one statement, so a code cannot go over its limit because two buyers checked out at the same moment. If it ran out while the buyer was filling the form, the increment does not happen.
A cancelled order gives the use back, once.
What the buyer is told
Each refusal has its own message, because "invalid code" sends the buyer to support:
| Situation | What it says |
|---|---|
| no such code | "No such promo code. Check it for typos." |
| outside its dates | "This promo code has expired." |
| total limit reached | "This promo code has been used as many times as allowed." |
| this buyer's limit reached | "You have already used this promo code." |
| wrong currency | "This promo code does not work in this currency." |
| under the minimum | "The promo code applies from {amount}." — with the amount formatted |
| misconfigured | asks the buyer to report it |
The minimum-amount message names the figure. "Does not apply" without the threshold is the same as no message at all: the buyer cannot act on it.
What promo codes are not
Worth reading before planning a campaign on them:
- No automatic discounts. Everything here needs a code typed in. There is no "20% off this category this week" without one.
- No codes scoped to a product or category. A code applies to the goods total, whatever is in the cart.
- No stacking. One code per order; two do not combine.
- No personal or cumulative discounts, no loyalty tiers, no referrals.
- No abandoned-cart recovery mail. The carts are in the database and the data is sufficient — nothing is written.
What is there without a code is the old price: fill old_price and the card prints it struck through, with the product deciding whether a discount exists. There are also two storefront sort presets built on it, "discounted first" and "in stock first", and the discount they sort by is a percentage, not an amount — the difference depends on the currency and on the price, while what gets advertised is "−30%".
A composite product has no discount at all
Deliberately. Its card does not print an old price — the per-variant prices differ — so letting it into the "discounted first" ordering would put a product with no struck-through price at the top of a discount shelf.
Site-specific conditions ("new customers only") go in the code's properties and are enforced by your own listener; the component does not interpret them.
Next
- Currencies — why amounts are named per currency
- Orders in the manager — the discount snapshot on the order