Concepts

The dashboard, the API and the MCP server all use the same small set of objects. This page names each one and follows a referral from first click to payout.

Three conventions hold everywhere:

• Ids carry a prefix, so you can tell what you're holding: prg_ is a program, part_ a partner, com_ a commission.
• Money is a whole number of the smallest unit, like cents or pence, beside its currency. So 2000 in USD is $20.00.
• Rates are basis points, hundredths of a percent. So 2000 means 20%.

The cast

Program (prg_). Your affiliate program, with its currency, cookie window, commission defaults, portal branding and terms. One organization can run several.

Partner (part_). A person or company promoting you. A partner is pending while waiting for review, then active, declined or suspended, and belongs to at most one group with any number of tags. A partner who has been paid, or has a payout on its way, can't be deleted, only suspended, so their payout history stays.

Group. A tier of partners with its own terms. For example: agencies at 30%, everyone else at 20%.

• A group decides what its partners earn and whether you review them first.
• Each group has its own signup link, so people land in the right tier on their own.

Tag. A label for finding partners again. Use tags to filter your list, and to point campaigns, notifications and resources at the right partners. A tag never changes what a partner earns. Groups do that.

Link and coupon. A partner's ways in.

• A link is yoursite.com/?ref=handle. Add a short-link domain and refer.yoursite.com/handle works too.
• A coupon is a Stripe promotion code tied to a partner. A sale that uses it is credited to that partner, even with no click.

Click (clk_). One visit through a partner link. It records the landing page and where the visitor came from. It also stores how long it keeps the credit for the partner (the attribution window), which is fixed the moment the click happens and never recalculated. The default is 60 days. Inside it, the first partner to send the visitor gets the credit.

Referral. The thread from visit to money. It starts as a visit, may become a lead, and turns converted when the customer first pays. Partners see the same steps in their portal, including how each referral was credited, so they never have to take tracking on trust.

Customer (cus_). A referred customer, tied to the partner who referred them. A customer has one of six statuses: lead, trial, active, cancelled, refunded, suspended.

Sale (sale_). One payment, with amount, tax and currency. By default we work out commission on revenue after tax, so you never pay a percentage of the VAT you collected for the tax office.

Commission (com_). What a sale earned a partner. Its status is pending (waiting for approval), approved, due (matured and payable), paid, rejected or voided. It also records the commission rule and branch that set its amount.

What a refund does depends on where the money is:

• Not paid yet: the commission is voided.
• In a payout that hasn't gone out: the payout shrinks to what's left, or is removed if nothing is.
• Already sent, or on its way: the commission stays, as a record of money that moved. We add a clawback instead. A clawback is a negative line against the partner's next balance.

A partial refund is your call. Let's say a $500 sale earned a $100 commission and you refund $50 of it: turn on Partial refunds take back the same share in Settings, under Commissions, and the commission drops by the same 10% to become $90. If it's already been paid, the partner gets a $10 clawback instead. Leave it off, which is the default, and any refund removes the whole $100.

Commission rule (flw_). What decides how much a sale earns. It has a trigger, an ordered list of branches (each a condition and a rate), and a fallback rate. Rules sort by priority, and when more than one could price a sale, the first rule that applies wins it. The id keeps its old flw_ prefix, because changing it would rewrite every commission's history. Commission rules covers them in full.

Payout (pyt_) and payout batch. When a period closes, commissions that have matured add up into one payout per partner per currency.

• It's sent on your NET term: 15, 30 or 60 days after the period ends.
• A partner who can't be paid is never dropped quietly. Their payout row exists as not_eligible, with the reason: no payout method, a missing tax form, or a balance under the minimum.
• You and the partner both see that reason.

The lifecycle, end to end

1. A visitor lands through ?ref=alice. The script records a click and sets the referral cookie.
2. They sign up. The referral becomes a lead. If you add them as a customer now, they're already tied to Alice.
3. They pay. Stripe tells us, and we record the sale.
4. Your commission rules price the sale into a commission for Alice.
5. The commission waits out your holding period, 14 days by default. That's your buffer for refunds.
6. You approve it, or your commission rule approves it for you. Once it matures, it's due.
7. The period closes, the NET term runs, and the commission goes into a payout. Your own PayPal or Wise account pays it.

Each step shows up in three places:

• It can send a message to your own server the moment it happens. That message is a webhook event.
• You can read it over the API.
• The partner sees it in their portal.

Live and test

Connect a test-mode Stripe account and the whole lifecycle runs on test data.

API keys come in two kinds, rail_live_ and rail_test_. Every API response says which kind made the call. Both read and write the same data. The prefix labels the key. It doesn't separate the rows.

Attribution works the same in test mode. One thing changes: a sale Stripe reports as test mode is marked as a test, and a marked sale never pays anybody. It shows up. It never becomes money.