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 an order 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 order, not here.
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 order. Issuing it is not enough.
Promotion or voucher? If it should apply to everybody during a period: promotion. If it should be tied to a person or campaign: voucher.