Rewards and referrals
Coupons, promo codes, free usage and referral programs.
rewards.create
{
"id": "launch",
"name": "Launch week",
"type": "percentage_discount",
"percent_off": 20,
"duration": "repeating",
"duration_cycles": 3,
"plan_ids": ["pro"],
"promo_codes": [{ "code": "LAUNCH20", "max_redemptions": 500, "expires_at": "2026-12-31T00:00:00Z" }]
}type | Extra fields | Effect |
|---|---|---|
percentage_discount | percent_off | Takes a share off the invoice lines for the plans in plan_ids, or every plan |
fixed_discount | amounts_off: [{ "currency", "amount" }] | Takes a fixed amount off |
feature_grant | grant: { "feature_id", "amount", "expires_in_days"? } | Adds to the balance now |
free_product | free_plan_id | Gives a plan or add on at no charge |
duration is once, repeating (with duration_cycles) or forever. Discounts are used up only when an invoice is paid.
rewards.redeem
{ "customer_id", "code": "LAUNCH20" }. A customer can use each reward once. You can also pass promo_code straight to billing.attach, and the hosted billing page has a code field.
rewards.list, rewards.get, rewards.update, rewards.delete
rewards.update takes { "reward_id", ...fields }. rewards.delete removes a reward nobody used, and archives it otherwise so its codes stop working.
Referral programs
{ "id": "friends", "name": "Invite a friend", "reward_id": "friend_credits", "referrer_reward_id": "thank_you_credits", "trigger": "checkout", "max_redemptions_per_code": 20 }- Your app asks for a code for each customer with
referrals.create_code({ "customer_id", "program_id" }). It is the same code every time. - When a friend signs up with it, call
referrals.redeem({ "customer_id": "<the friend>", "code" }). - With
trigger: "signup"both rewards go out at once. Withcheckoutthey go out when the friend pays their first invoice, optionally only for plans intrigger_plan_ids.
Customers cannot use their own code, and each friend can be referred once per program. referrals.list_programs, referrals.get_program (with code and reward counts), referrals.update_program and referrals.delete_program manage programs.