---
title: "Referral codes and affiliates"
url: /commerce/referrals
---

# Referral codes and affiliates

> Credit for a Customer who brings another, and cash for an affiliate who brings many: codes, attribution, holds against refunds, payouts and abuse checks.

A referral code pays two Customers in credit when the new one pays. An affiliate earns a cash share of what its Customers pay.

```mermaid title="A referral, from the click to the credit"
stateDiagram-v2
  [*] --> clicked: a shared link
  clicked --> signed_up: inside the window
  signed_up --> qualified: first payment
  qualified --> rewarded: no refund
  signed_up --> void: own account
  qualified --> void: refunded
```

## One referral, day by day
Every Customer has one code and one link on its own [Host](/reference/platform.md#host), in the portal and over MCP.

| Day | What happens | What each side sees |
| --- | --- | --- |
| 1 | A member shares `https://briefs.apis.dev/r/DANA-7KQ` | The member's portal counts a click |
| 3 | A friend signs up through the link, inside `window` | The friend's Checkout shows the code and the credit it brings |
| 3 | Ito's first charge clears | The referral is `qualified`; both credits wait out the refund window |
| 17 | No refund arrived | The friend gets `give` and the member gets `get`, each on its credit balance, each with a receipt line |

Attribution is first touch: the first code inside `window` wins, a later click never takes it over. A code typed at Checkout counts the same as the link.

## Codes that cannot be farmed
A bad code answers 422 [`referral_invalid`](/reference.md#referral_invalid): the account's own, unknown, outside its window, or from a referrer at `max`.

The sign-up goes on without the credit. Every referral feeds the [risk signals](/trust/fraud.md#signals). A card, a device or a network the two accounts share voids it before any credit lands.

An affiliate's links carry its disclosure on every page they open. An affiliate that breaks the terms is closed, its pending commissions reversed.

## Affiliates, paid in cash
An affiliate need not be a Customer. It applies on the site and agrees to the program's terms.

You approve it, or `approve: 'any'` admits every applicant.

| | A referral code | An affiliate |
| --- | --- | --- |
| Who shares it | Any Customer | An approved affiliate, a person or a business |
| What it earns | Credit, once, by `offer.referrals` | Cash, `share` of each charge's net revenue for `months` |
| When it is paid | After the refund window | Each [commission](/commerce/referrals.md#affiliates) after `hold`, once the balance passes `min` |
| How it is paid | The credit balance | A payout to the affiliate's own Stripe account |
| What reverses it | A refund in the window | A refund or a dispute inside `hold` |
| Plan it needs | Launch and above | Team and above |

A commission is `pending` while its hold runs, then `payable`, then `paid`; a refund inside the hold makes it `reversed`. Stripe's payout fees pass through at cost.

## The Offer that runs both
The weekly brief gives each side of a referral 5 in credit. Affiliates earn a fifth of what their members pay for a year.

```ts title="definition.ts"
import { define, generative } from 'apis.dev'

/** A weekly brief on the software companies that changed headcount, for members and their agents. */
export default define({
  name: 'briefs', domain: 'briefs.apis.dev',
  sources: {
    firms: { api: 'companyfacts.apis.dev', cost: { 'Company.search': 0.005 } },
  },
  Issue: {
    week: 'string!#', title: 'string', body: 'markdown',
    status: {
      draft:   { run: generative('This week in {firms}: who hired, who shrank') },
      review:  { in: 'drafted', role: 'editor' },
      publish: { in: 'reviewed', role: 'editor' },
      send:    { in: 'published', to: 'Member' },
    },
  },
  on: { 'every Mon 06:00': 'Issue.draft', 'Issue.published': 'Issue.send' },
  offer: {
    'Issue.list': 0, 'Issue.read': 0.25,
    Member: { month: 8, includes: { 'Issue.read': 'all' } },
    referrals:  { give: 5, get: 5, after: 'paid', window: '30d', max: 20 },
    affiliates: { share: 0.2, months: 12, hold: '30d', min: 50 },   // Team and above
  },
})
```

A member's agent reads its own code and earnings with `getReferral` over MCP, or from the portal's API.

```http title="Response"
HTTP/1.1 200 OK
Content-Type: application/json
X-Cost: price=0, currency="USD"
X-Request-Id: req_3c81e0f7a24b96d5e1a0

{
  "code": "DANA-7KQ",
  "link": "https://briefs.apis.dev/r/DANA-7KQ",
  "clicked": 41,
  "signedUp": 4,
  "rewarded": 3,
  "earned": { "credits": 15, "currency": "USD" },
  "left": 17
}
```

Your side reads every referral with `Referral.list`, and every affiliate and commission with `Affiliate.list` and `Commission.list`, on the [Operator plane](/trust/planes.md).