Promotions & vouchers
Overview
Two related but different things:
- A promotion is a period with a name — under it, items and categories become cheaper. It works
automatically for everybody buying during that time.
- A voucher is a discount code that makes a document — quote, order or invoice — cheaper. It
only works when somebody redeems it.
The difference is not pedantry: a promotion needs nobody to type anything; a voucher needs exactly that.
Core tasks
Create a promotion. Name, period and the items or categories affected. After the period the promotion ends by itself — that is the point of the period.
Issue vouchers. Discount codes with their conditions. Redemption happens on the document, not here: in the "Voucher" card on the quote, the order or the invoice (draft only).
Pass a voucher on. When a quote becomes an order, the redeemed voucher moves along — from then on it is revoked on the order. If a document ends without a deal (quote rejected, expired or revised, order or invoice cancelled), the voucher gets its value back. A revision or renewal does not carry the voucher line over; the code is redeemed there again.
How much a voucher covers. A value voucher covers the document's total: goods value minus the document discount plus the surcharge at document level (a rush surcharge on the quote, for instance). If the balance is sufficient, the customer does not pay the surcharge either. A percentage voucher, by contrast, only applies to the goods value — the surcharge is not goods. Never more than the document allows is credited; the rest stays on the voucher.
If the document becomes smaller afterwards. If you lower or remove a line item after redeeming, or lower the surcharge, the deduction automatically drops to the new total — the document total never becomes negative. The difference goes back onto the voucher as balance, and the "Voucher" card on the document shows by how much it was reduced. If several vouchers are redeemed, the most recently redeemed one is reduced first. A document discount yields to the redeemed voucher: if the document no longer covers both, the discount is capped first, the voucher only once goods value and surcharge alone are no longer enough. The voucher lines per tax rate follow the new shares; a tax rate without line items loses its voucher line. If the document grows again later, the deduction does not grow by itself — revoke the voucher and redeem it again.
Know the tax rule. The application says it itself: one voucher line per tax rate — so that VAT comes out right. A discount on an order containing 7 % and 19 % cannot be expressed in a single line without making the tax wrong. Hence several lines appear; that is correct and not a display fault.
Fields in detail
Promotion
| Field | Required | Values / format | What it does |
|---|---|---|---|
Name name | yes | text, max. 160 characters | What the promotion is called. It appears as its own line on the document — the customer reads this name. |
Description description | no | text | What the promotion is for. |
Rules rules | yes | conditions and discount | When it applies and what it grants — say "from 3 pieces, 10% on the category". |
Customer group customerGroupId | no | an existing group | Who it applies to. Empty means everyone. |
Rank priority | no | number | What wins when several promotions match. |
Valid from / to validFrom, validTo | no | date | The promotion period. |
Brand brandId | no | one of your brands | For which brand. |
Active active | no | yes/no | Whether the promotion applies. |
A granted discount is reported as a document line per tax rate. That is not cosmetic but the precondition for the tax report being correct when a basket contains several rates.
Voucher
| Field | Required | Values / format | What it does |
|---|---|---|---|
Code code | no | text, max. 40 characters | The redemption code. Left empty the system generates them. |
Number of codes codeCount | no | 1 to 500 | How many individual codes are generated. Individual codes can be tracked per recipient; a shared one cannot. |
Label label | no | text, max. 160 characters | What the voucher is called on the document. |
Voucher kind kind | no | discount or credit | A discount reduces the taxable base — VAT drops proportionally. A credit is a sold value voucher and acts like a payment on redemption; the tax arises when the goods are sold. Discounts apply on documents only, credit at the point of sale only. Default: discount. Cannot be changed after the first redemption. |
Type rateType | yes | amount or percent | Whether a fixed amount or a share is deducted. A credit is always an amount. |
Value valueAmount | yes | greater than 0 | How much. |
Maximum discount maxDiscountAmount | no | amount, 0 or more | Caps a percentage voucher. Without this limit a 20% voucher on a large order costs a multiple of what was intended. |
Minimum order value minOrderAmount | no | amount, 0 or more | From what value it can be redeemed. |
Customer customerId | no | an existing customer | Binds the voucher to a person. Empty means anyone with the code. |
Maximum redemptions maxRedemptions | no | number, 0 or more | How often it may be redeemed in total. The second guard against a code passed around. |
Valid from / to validFrom, validTo | no | date | Redemption period. |
Brand brandId | no | one of your brands | For which brand. |
Active active | no | yes/no | Whether the voucher can be redeemed. |
Settings & permissions
- Module
module.promotions. promotions.campaign.view/.managefor promotions, **promotions.voucher.view/
.manage** for vouchers.
- Promotions intervene in price determination, see Prices & units.
- Calculation happens in the core, see commerce core.
FAQ & troubleshooting
The promotional price does not appear. Check the period — and whether the item or category really belongs to the promotion.
An order shows several voucher lines. By design: one line per tax rate. Anything else would produce wrong VAT.
The voucher has no effect. It has to be redeemed on the document. Issuing it is not enough. Credit notes and cost documents (dunning or chargeback costs) take no voucher.
The voucher line cannot be deleted. By design: amount and tax rate come from the redemption. It is removed via "Revoke" in the "Voucher" card — which also gives the voucher its value back.
Promotion or voucher? If it should apply to everybody during a period: promotion. If it should be tied to a person or campaign: voucher.