Promotion effects
An effect is what a promotion does once a customer holds it and qualifies. Eligibility decides whether; the effect decides what.
There are seven kinds. Each has its own fields, and picking the wrong one is the usual reason a discount lands somewhere unexpected.
Money off
Percentage discount
A percentage off. rate is required.
Code
Two fields keep it from running away. max_discount caps the amount in currency
terms, so 10% off never exceeds, say, CHF 200. cap_per_invoice caps the total
across all lines when apply_per_line is on.
scope decides what it applies to: the whole invoice or specific lines.
Fixed discount
A flat amount off. amount is required.
Code
That flag is the one to read twice. On a four-line invoice it is the
difference between CHF 50 and CHF 200. Use cap_per_invoice if you turn it on.
Price override
Replace the rate outright rather than discounting it. override_amount is
required, and the customer pays exactly that, whatever the catalog says.
Use it for a negotiated rate expressed as a promotion; it ignores the tier ladder entirely.
Free things
Free periods
Whole billing periods at no charge. periods is required.
Code
This is the free-trial effect. The subscription still exists and still bills afterwards; only the charge is waived.
Free product
A given quantity of a product, free. product_id is required, quantity
defaults to one.
This is the effect behind "buy A and B, get C free". Pair it with a
product_combination condition, described in Promotion rules.
Usage credits
Free units of a metered product. product_id and quantity are both required.
Code
Different from free periods: the customer still pays for everything past the credited amount, in the same period.
Balance
Wallet credit
Money into the customer's wallet. amount is required.
The credit sits as balance and is spent by future invoices. Nothing is discounted, so this is the right effect for goodwill and referral rewards, where you want the money to be usable rather than tied to one bill.
Choosing between them
The three that get confused:
| You want | Use | Because |
|---|---|---|
| The next invoice to be smaller | percentage_discount or fixed_discount | It reduces the bill directly |
| The customer to owe nothing this period | free_periods | It waives the charge, not the subscription |
| The customer to have money to spend | wallet_credit | It becomes balance, not a discount |
apply_per_line multiplies
fixed_discount and percentage_discount both accept apply_per_line. With it
on, the effect applies to each matching line rather than once to the invoice.
Always pair it with cap_per_invoice.
Combining effects
A promotion can carry several effects at once: effects[] is an array. A
welcome offer might grant free periods and wallet credit.
For rewards that change as a customer grows, use phases[] instead of effects[]
— an ordered ladder with its own effects per phase. The two are mutually
exclusive; effects is the single-phase shorthand.
Reference
| Topic | When you need it |
|---|---|
| Promotion rules | The conditions that decide who qualifies |
| Promotions | Distribution, budgets and the lifecycle |
| Wallets | Where wallet_credit lands |
| Promotions API | Every effect variant and its fields |