Skip to content

Referral codes and affiliates

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

A referral, from the click to the credit

One referral, day by day

Every Customer has one code and one link on its own Host, in the portal and over MCP.

DayWhat happensWhat each side sees
1A member shares https://briefs.apis.dev/r/DANA-7KQThe member's portal counts a click
3A friend signs up through the link, inside windowThe friend's Checkout shows the code and the credit it brings
3Ito's first charge clearsThe referral is qualified; both credits wait out the refund window
17No refund arrivedThe 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: 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. 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 codeAn affiliate
Who shares itAny CustomerAn approved affiliate, a person or a business
What it earnsCredit, once, by offer.referralsCash, share of each charge's net revenue for months
When it is paidAfter the refund windowEach commission after hold, once the balance passes min
How it is paidThe credit balanceA payout to the affiliate's own Stripe account
What reverses itA refund in the windowA refund or a dispute inside hold
Plan it needsLaunch and aboveTeam 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.

definition.ts
25 lines
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.

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.