Skip to content

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 ​

FieldWhat it does
codewhat the buyer types. Unique across the shop
typepercent or fixed
percentthe percentage, 0–100, for percent
discountsthe amount per currency, for fixed
currencieswhich currencies it works in. Empty means all
min_amountthe minimum goods total, per currency
starts_at / ends_atvalidity. Empty at either end means open-ended
usage_limithow many times in total
usage_limit_per_userhow many times per buyer
usedthe counter, for reading
published_atan 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:

SituationWhat 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
misconfiguredasks 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 ​

pbShop — a shop component for PageBlocks