Run your program
Commission rules
Caps, first-payment rates, per-product rates, bonuses, level-ups and Stripe promotion codes.
Set these in Settings → Commission rules → Advanced rules, or send commission_extras to PATCH /api/v1/program (it replaces the whole set). All are optional and apply to payments from now on. Commissions already earned keep their amount.
Which rate applies
- A product rule: an exclusion or the product's own rate. It beats an affiliate's custom rate, so a low-margin product stays protected.
- The first-payment rate, on a customer's first payment. It never lowers an affiliate's custom rate.
- The affiliate's custom rate.
- The program's rate.
Limits
| Field | What it does |
|---|---|
min_transaction_cents | Smaller payments earn nothing |
max_payments_per_customer | Commissions stop after this many payments from one customer. A refunded payment still counts |
cap_per_customer_cents | The most one customer can earn an affiliate |
cap_per_affiliate_cents | The most one affiliate can earn in total, bonuses included |
A commission that would pass a cap is lowered to fit. Refunds free up room. If a payment is in another currency, the limit can't be compared, so the commission waits for your approval with the currency_mismatch flag.
Per-product rates
product_rules takes { "product": "price_123", "value": 10 } or { "product": "prod_9", "exclude": true }. Match on any id your provider sends: Stripe product or price, Polar product or price, Lemon Squeezy product or variant, Paddle product or price, Creem product, Dodo product. For server-side sales, send product_id.
- When a payment has several products, the first matching rule in your list decides the whole payment.
- A renewal that names no product uses the product the customer last paid for.
- No product id at all means your normal rate. Stripe one-time Checkout webhooks don't list products: put
referralmeter_productin the session metadata.
Bonuses
bonuses takes { "metric": "sales", "threshold": 1, "amount_cents": 5000 }. Sales with a threshold of 1 is a first-sale bonus. metric is sales or revenue (customer revenue in cents, in your program currency).
- Only sales that earned a commission count. Flagged sales count once you approve them.
- A bonus is paid once, when the threshold is crossed. An affiliate already past it when you add the rule isn't paid for it.
- If refunds or rejections drop the affiliate below the threshold, the bonus comes back: cancelled if unpaid, otherwise taken off their next payout. Crossing it again earns it again.
Level-ups
levels takes { "metric": "sales", "threshold": 25, "value": 40 }. When an affiliate reaches it, their custom rate rises to value for future payments.
- Past commissions are never rewritten, including the sale that reached the level.
- A level never lowers a rate. Refunds don't move anyone back down.
- If you lower a level-up by hand, the same level won't raise it again.
- An affiliate on a flat custom rate stays there when your program pays a percent, because the two can't be compared.
Ad traffic
flag_paid_traffic and flag_brand_bidding send matching sales to approval. See Fraud & approvals.
Stripe promotion codes
On an affiliate's page, Create in Stripe makes the discount and the code in your Stripe account, and credits sales using it to that affiliate. Stripe needs a discount on every promotion code. For a code with no discount, add it by hand.
This needs Stripe connected with a restricted key, and that key needs Coupons: Write and Promotion Codes: Write as well as Webhook Endpoints: Write. If it can't, you get a message saying which permissions to add, and nothing is created. Neither permission can move money. Removing a code here switches it off in Stripe.
The same thing is POST /api/v1/affiliates/{id}/promo-codes and the create_stripe_promo_code MCP tool, with a key that has the payouts scope. In the dashboard it's for the owner.