Demo docs: examples are illustrative.
Referral API

Rewards

Cash, credits, perks, and recurring commissions, with your own rules.

A reward is something you owe a person. Referral API works out the amount and tracks its status. You decide how to deliver it.

Reward types

Cash

Paid by bank transfer, PayPal, or gift card. You record the payout.

Account credit

You apply it in your billing system when it unlocks.

Perk

A non-monetary benefit, such as a free month or extra seats.

Commission

A percentage of each payment, for a limited number of months.

How commissions are calculated

Commissions use the net payment amount: after tax, discounts, and refunds. For a payment pp, commission rate rr, and fees ff:

commission=r×(p−f)\text{commission} = r \times (p - f)

Over a commission period of nn months, the referrer earns:

total=∑i=1nr×(pi−fi)\text{total} = \sum_{i=1}^{n} r \times (p_i - f_i)

A 20% commission on a $49 plan with $4.41 in tax for 12 months comes to 0.2×(49−4.41)×12=$107.020.2 \times (49 - 4.41) \times 12 = \$107.02.

Caps and limits

You can cap rewards per referrer, per month, or across the whole program. When a cap is reached, new rewards are recorded at $0 with a capped note, so the history stays complete.

Example rule
{
  type: 'commission',
  rate: 0.2,
  months: 12,
  cap: { per: 'referrer', amount: 50000 }, // $500 in cents
}

Statuses

  • Pending: calculated, but waiting for the hold period.
  • Unlocked: ready for you to pay.
  • Paid: you recorded a payout.
  • Reversed: a refund or dispute cancelled some or all of it. See the ledger.

How is this guide?

Referrals

How a visit becomes a referral, and the states it moves through.

Reward ledger

A double-entry record of every reward, payout, and reversal.

On this page

Reward typesHow commissions are calculatedCaps and limitsStatuses