---
title: "One page of the caller's referred users, newest first (spec 4.7)."
method: GET
path: "/api/v1/affiliate/referrals"
tags: ["Affiliate"]
---

# One page of the caller's referred users, newest first (spec 4.7).

`GET /api/v1/affiliate/referrals`

## Request

- Base URL: `https://api.avatarfactory.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.avatarfactory.io/api/v1/affiliate/referrals`
- Auth: one of:
  - API key in cookie `session`
  - HTTP bearer

<br/>Emails are masked in the service. `gross_revenue_cents` is the sum of the<br/>invoice bases booked for that referral, before refunds;<br/>`net_commission_cents` is the signed ledger total, so it drops when a<br/>claw-back lands while the revenue column keeps the historical figure.<br/>`status` is the six-word vocabulary (spec 1.3) and `total` counts every<br/>referral, not the page.

## Query parameters

- `cursor` integer, nullable
- `limit` integer

## Response `200`

OK

- ReferralsResponse: One page of referrals, plus how many there are in total. `total` counts every referral this affiliate has, not the page, so the heading can say "12 referrals" while the table shows the newest 25.
  - `items` ReferralItem[]
    - `first_paid_at` string, date-time, nullable
    - `gross_revenue_cents` integer, required
    - `interval` string, nullable
    - `last_paid_at` string, date-time, nullable
    - `masked_email` string, required
    - `net_commission_cents` integer, required
    - `plan_slug` string, nullable
    - `signed_up_at` string, date-time, nullable
    - `status` 'signed_up' | 'trial' | 'paying' | 'past_due' | 'churned' | 'refunded', required
  - `next_cursor` integer, nullable
  - `total` integer

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/avatarfactory/apis/avatarfactory-api.md) · [All operations](https://skmtc.dev/avatarfactory/apis/avatarfactory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/avatarfactory/apis/avatarfactory-api/revisions/66fc7aa3f296?raw)