---
title: "List Referrals"
method: GET
path: "/admin/billing/referrals"
tags: ["admin", "billing"]
---

# List Referrals

`GET /admin/billing/referrals`

## Request

- Base URL: `https://api.excellence-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.excellence-ai.com/admin/billing/referrals`
- Auth: OAuth 2
  - Password
  - Token URL: `api/login`

Parrainage (EXC-1858): every referral, newest first.

## Query parameters

- `status` 'attached' | 'week_granted' | 'paid' | 'month_granted' | 'blocked_same_card' | 'canceled' | 'capped'
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- AdminReferralsResponse
  - `total` integer, required
  - `items` AdminReferralResponse[], required
    - `id` string, required
    - `code` string, required
    - `status` 'attached' | 'week_granted' | 'paid' | 'month_granted' | 'blocked_same_card' | 'canceled' | 'capped', required
    - `referrer` ReferralPerson, required
      - `user_id` string, required
      - `name` string, nullable
      - `email` string, nullable
    - `referee` ReferralPerson, required
      - `user_id` string, required
      - `name` string, nullable
      - `email` string, nullable
    - `created_at` string, date-time, required
    - `week_granted_at` string, date-time, nullable, required
    - `paid_at` string, date-time, nullable, required
    - `month_due_at` string, date-time, nullable, required
    - `month_granted_at` string, date-time, nullable, required
    - `referee_week` Reward, required
      - `kind` 'grant' | 'credit', required
      - `at` string, date-time, required
      - `grant_id` string, nullable
      - `ends_at` string, date-time, nullable
      - `credit_cents` integer, nullable
      - `customer_id` string, nullable
    - `referrer_week` Reward, required
      - `kind` 'grant' | 'credit', required
      - `at` string, date-time, required
      - `grant_id` string, nullable
      - `ends_at` string, date-time, nullable
      - `credit_cents` integer, nullable
      - `customer_id` string, nullable
    - `referrer_month` Reward, required
      - `kind` 'grant' | 'credit', required
      - `at` string, date-time, required
      - `grant_id` string, nullable
      - `ends_at` string, date-time, nullable
      - `credit_cents` integer, nullable
      - `customer_id` string, nullable

## Other responses

- `422`: Validation Error

## Changes

> 106 revisions in range; 1 not diffed.

- **2026-11-12** `0af74c49ba7a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/excellence-ai/apis/excellence-learning/changes/admin/billing/referrals/get.md)

---

[API](https://skmtc.dev/excellence-ai/apis/excellence-learning.md) - [All operations](https://skmtc.dev/excellence-ai/apis/excellence-learning/llms.txt) - [OpenAPI document](https://skmtc.dev/excellence-ai/apis/excellence-learning/revisions/de6afcc9656f?raw)
