Promotions
A promotion reduces what a customer pays: a percentage off, a fixed amount, free units of a metered product, a free billing period, or wallet credit. The engine evaluates it while the invoice is being built, so the discount appears as part of normal billing rather than as a manual adjustment afterwards.
A promotion is two things bolted together. Eligibility decides which customers and which lines it may touch. Effects decide what it does to them. Between those sits the question that governs everything else on this page: how does a customer come to hold it at all?
How customers get it
This is the distribution field, and it is required at creation. The
dashboard asks it as "Who gets it, and how?" on the second step of the builder.
Available to the audience
distribution: "AUTO_APPLY". Eligible customers get it when they redeem it, or
when an operator attaches it.
Once held, it applies automatically at billing. No code is involved.
This is the default and the right answer for most promotions.
Auto-enrol everyone
distribution: "AUTO_ENROLL". Every member of the audience is enrolled without
doing anything, unless they opt out. Use it for a blanket price change dressed as a promotion, or a goodwill
credit you do not want customers to have to claim.
Customers redeem a code
distribution: "COUPON". The customer types a code to opt in. code becomes required, and it must be
unique across your organisation.
Attached directly
distribution: "DIRECT". Operator-attached only, with no audience and no code. It exists in the API but
the builder does not offer it; reach for it when a support agent grants
something one-off.
Two names the old documentation got wrong
The field is distribution, not visibility, and its values are the four above.
The lifecycle endpoints are POST /v1/promotions/{id}/publish and
/archive — there is no activate or deactivate.
Create it in the dashboard
The builder is a six-step wizard: Goal → Audience → Rule → Name & dates → Limits → Review. It asks for a goal first and then only shows the fields that goal needs.
-
Open the builder
In the sidebar under Advanced, click Promotions, then Create Promotion.
-
Pick what you are trying to do
The Goal step offers presets: a discount, credit or free units, a free trial, a product or variant bundle reward, spend and usage ladders, or Build the rule yourself when none of them fit.
The goal only shapes the questions you are asked next -
Set the audience and distribution
Answer "Who gets it, and how?", then narrow the audience to Every customer or Customers matching rules. The builder shows a live count of how many customers match, which is the cheapest sanity check available.
-
Define the rule, dates and limits
The Rule step builds eligibility and effects. Name & dates sets
valid_from, which is required. Limits caps the damage: a total budget, a cap on redemptions overall, and a cap per customer. -
Review and publish
A promotion starts as a Draft and discounts nothing. Publishing is what puts it in front of customers.
Create it with the API
name, distribution and valid_from are required. Everything else is
optional, and a promotion is created as a draft.
Try it before you publish it
POST /v1/promotions/simulate runs a promotion against a hypothetical invoice
and POST /v1/promotions/{id}/preview runs one against a real customer, both
without redeeming anything. On a promotion with a budget, that is a great deal
cheaper than finding out from the invoices.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| "Who gets it, and how?" | distribution, required |
| Available to the audience | "AUTO_APPLY" |
| Automatically enroll everyone | "AUTO_ENROLL" |
| Customers redeem a code | "COUPON", with code |
| Limits → total budget | max_budget in major units, plus budget_currency |
| Limits → what happens when it runs out | budget_behavior: SKIP or PARTIAL |
| Limits → per-customer cap | max_redemptions_per_customer |
| Type column in the list | archetype, a builder preset hint only; it is not rule logic and does not affect billing |
| Draft → Active | POST /promotions/{id}/publish |
Where promotions go next
- Publish it. A draft discounts nothing.
- Watch the budget.
GET /v1/promotions/{id}/redemptionslists who has taken it; the list page has Budget exhausted and Redemptions exhausted filters for the same reason. - Understand stacking before running two at once.
stacking_modeisstackby default;exclusivemakes a promotion refuse to share an invoice.
Next step
Promotions apply while an invoice is built. Continue to Invoices to see where they land.
Going deeper
A promotion is two mechanisms bolted together, and each has its own page.
| Topic | What it adds |
|---|---|
| Promotion effects | The seven things a promotion can do, from a percentage off to wallet credit |
| Promotion rules | The eight conditions that decide who qualifies, and how they combine |
Reference
| Topic | When you need it |
|---|---|
| Audiences | Reusable customer populations shared across promotions |
| Scheduled changes | Publishing, versioning and cancelling a promotion version |
| Wallets | Where credit-granting promotions deposit |
| Promotions API | Every field, plus simulate, preview, redeem and tokens |