Copy page

Promotions in depth

Promotion effects

What a promotion does once a customer holds it and qualifies is its shape. Eligibility, audience and scope decide whether; the shape decides what.

There are six shapes. shape.kind names one, and the shape's own fields sit beside it. A promotion has exactly one shape, and it is frozen once the promotion is published. Picking the wrong one is the usual reason a discount lands somewhere unexpected.

✕

Money tables

Every money amount in a shape (amount, min_spend, threshold_spend, reward_amount) is a money table: an optional currency-less default spent in whatever currency the bill is in, plus entries of {currency, value} that win for the currencies they name. A bill in a currency the table neither lists nor covers with a default records a non-firing rather than spending another currency's value.

Code
{ "default": "50", "entries": [ { "currency": "CHF", "value": "48" } ] }

Money off a line: line_discount

Cuts each matching line. discount_kind says how:

discount_kind	Field	What the customer pays
percent	percent, in (0, 100]	the line less that share
fixed	amount, a money table	the line less that amount
override	amount, a money table	that price instead, never more than list

Code
percent 10  on a line of CHF 2,180.00   ->  CHF 218.00 off

first_n_periods limits the cut to the redemption's first n billing periods. min_spend makes it fire only when the bill's net before any promotion reaches an amount. A fixed cut applies to each matching line, so narrow it with scope and cap the total with an amount ceiling in limits (see Promotions).

Use override for a negotiated rate expressed as a promotion. A price agreed in a deal is better stated on the subscription itself, as an agreed price on the line (see Subscriptions); negotiated_prices decides whether a promotion may cut such a price at all.

Free things

Free periods: free_periods

Whole billing periods at no charge. periods is required.

Code
periods 1   ->  the first billing period is free
periods 3   ->  the first three are free

A period is spent only when money actually moved: a line that was already zero costs no period. The subscription still exists and still bills afterwards; only the charge is waived. A trial that is part of the deal itself is better written as a phase at a free price on the subscription.

Free units: free_units

Free units of a product. product, units and units_window are required; price_key narrows it to one keyed price.

Code
units 10000  units_window per_period   ->  usage is billed only above 10,000 each period
units 10000  units_window lifetime     ->  the first 10,000 ever are free

The customer still pays for everything past the free units, in the same period.

Bundles: bundle

A reward on a target line when every leg of a set is present. The reward is free (the target's units cost nothing), percent (reward_percent, applied to the rewarded units only) or fixed (reward_amount per unit). repeat is once or per_set, and grace lets the legs arrive days apart. See Promotion rules.

Rewards for volume

Threshold: threshold

A percent cut once a measure (units or spend) reaches threshold_units or threshold_spend within a window (lifetime, billing_period, calendar_month, calendar_year, or first_n_periods with first_n_periods). A line gets the cut only if the measure before it already reached the threshold.

Rebate: rebate

The same measure and window, but when the threshold is reached the whole window is rebated by percent, including what was billed before the crossing.

How shapes combine

When several promotions fire on one bill, they run in four lanes, in a fixed order, each seeing the net the previous one left:

1. zeroing: free_periods, free_units, and a bundle with a free reward
2. price_cut: line_discount, and a bundle with a percent or fixed reward
3. threshold
4. rebate

never_with on a promotion names promotions it may never fire alongside. Every row of GET /v1/invoices/{id}/promotions carries the lane that produced it.

Choosing between them

The ones that get confused:

You want	Use	Because
The next invoice to be smaller	line_discount	It reduces the matching lines directly
The customer to owe nothing this period	free_periods	It waives the charge, not the subscription
Usage free up to an allowance	free_units	Only the units past the allowance are billed
Bigger customers to pay less per unit	threshold or rebate	They reward reaching a volume

Goodwill or welcome credit that the customer can spend over several invoices is not a promotion shape: grant it as price-reduction credit on their wallet (a credit with source PROMOTION).

Reference

Topic	When you need it
Promotion rules	Audience, eligibility, scope and shape conditions
Promotions	Distribution, window, limits and the lifecycle
Wallets	Price-reduction credit
Promotions API	Every shape and its fields