Promotion rules
A promotion's eligibility decides who qualifies. It is a set of conditions plus a mode saying how they combine.
Code
Eight condition kinds exist. Most promotions use one; the interesting ones use two.
Spend and quantity
Minimum spend
Qualifies when the bill reaches an amount. amount and currency are required.
Code
max_amount closes the top end, which is how you build a band rather than a
floor. scope decides whether the total is the invoice or a subset of lines.
Quantity threshold
Qualifies on how many units of given products are being bought. product_ids and
min_quantity are required.
Code
max_quantity bounds it, so a reward can target 10–50 seats and stop.
Usage threshold
The same idea against metered consumption rather than declared quantity. Use it for growth rewards: cross 1,000,000 API calls and something happens.
Who the customer is
First purchase
Qualifies only on a customer's first purchase. No fields; it is either in the set or it is not.
The welcome-offer condition. Pair it with free_periods for a first-month-free
promotion.
Subscription plan
Qualifies only for customers on given plans. Use it to make an offer that exists for one tier only, or to exclude a legacy plan from a repricing.
External verification
Qualifies only when a customer holds a verification of a given type.
verification_type is required.
This is how student, non-profit and reseller pricing is expressed: the verification is the proof, and the promotion reads it.
What they are buying
Product combination
Qualifies when specific products appear together. products is required.
Code
The grace fields (grace_period_days, grace_window_count, grace_anchor)
handle the awkward real case: the products are bought days apart rather than on
one invoice. Without a grace window, they must land together.
Key combination
The same idea for keyed products, matching on price_key rather
than product. product_id and keys are required.
Code
repeat_mode and max_multiple decide whether the reward repeats when a
customer qualifies several times over. A registrar giving one free domain per
matched pair, capped at five, sets both.
Combining conditions
mode: "ALL" is the default and the right answer nearly always. ANY is for
genuine alternatives: qualify by spend or by seat count.
An audience with no rules is refused, not read as everyone
The builder says this explicitly. To mean "everyone", choose Every customer rather than leaving the rules empty. An empty rule set is treated as a mistake, because it usually is one.
Before publishing anything with a budget, POST /v1/promotions/simulate runs the
rules against a hypothetical invoice and tells you what would happen. On a
promotion whose eligibility you are unsure about, that is a great deal cheaper
than finding out from the invoices.
Reference
| Topic | When you need it |
|---|---|
| Promotion effects | What happens once a customer qualifies |
| Promotions | Distribution, budgets and the lifecycle |
| Key sets | The keys key_combination matches on |
| Promotions API | Every condition variant, plus simulate and preview |