# Referrals

> Create, retrieve, and list referral records tracking customer-to-customer referrals.

A referral tracks when one customer (the referrer) brings a new customer (the referred) to your
platform. Referrals move through a lifecycle from `pending` to `qualified` to `rewarded` as the
referred customer meets your program's conditions.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The referral object

- **id** `string` — Unique identifier for the referral, e.g. `ref_2Dm5kW`.
- **referrer\_customer** `object` (expandable) — The customer who made the referral. Expand to retrieve the full customer object.
  - **id** `string` — Customer identifier, e.g. `cust_8aZ2`.
  - **email** `string` — Email address on the customer record.
- **referred\_customer** `object` (expandable) — The customer who was referred. Expand to retrieve the full customer object.
  - **id** `string` — Customer identifier, e.g. `cust_9bY3`.
  - **email** `string` — Email address on the customer record.
- **status** `enum` — One of `pending` (referred customer signed up), `qualified` (referral conditions met), or
  `rewarded` (reward has been issued to the referrer).
- **reward\_amount** `integer` — The reward value issued to the referrer in the smallest currency unit, once the referral reaches
  `rewarded` status. `null` until that point.
- **created** `integer` — Unix timestamp when this referral record was created.

## Create a referral

Record a new referral by providing the referrer and referred customer IDs. The referral starts in
`pending` status and transitions automatically as conditions are met.

`POST /v1/referrals`

```bash
curl -X POST https://api.vinr.com/v1/referrals \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d referrer_customer=cust_8aZ2 \
-d referred_customer=cust_9bY3
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const referral = await vinr.referrals.create({
referrer_customer: 'cust_8aZ2',
referred_customer: 'cust_9bY3',
});
```

```python
import vinr

referral = vinr.Referral.create(
  referrer_customer="cust_8aZ2",
  referred_customer="cust_9bY3",
)
```

```ruby
referral = Vinr::Referral.create(
referrer_customer: 'cust_8aZ2',
referred_customer: 'cust_9bY3',
)
```

```json
{
"id": "ref_2Dm5kW",
"referrer_customer": "cust_8aZ2",
"referred_customer": "cust_9bY3",
"status": "pending",
"reward_amount": null,
"created": 1716300000
}
```

## Retrieve a referral

Fetch a referral by its ID. Expand `referrer_customer` or `referred_customer` to include the full
customer objects inline.

`GET /v1/referrals/{id}`

```bash
curl https://api.vinr.com/v1/referrals/ref_2Dm5kW \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const referral = await vinr.referrals.retrieve('ref_2Dm5kW');
```

```python
import vinr

referral = vinr.Referral.retrieve("ref_2Dm5kW")
```

```ruby
referral = Vinr::Referral.retrieve('ref_2Dm5kW')
```

```json
{
"id": "ref_2Dm5kW",
"referrer_customer": "cust_8aZ2",
"referred_customer": "cust_9bY3",
"status": "qualified",
"reward_amount": null,
"created": 1716300000
}
```

## List referrals

Returns a paginated list of referrals. Filter by `referrer_customer` to see all referrals made by a
specific customer.

| Parameter           | Type    | Description                                           |
| ------------------- | ------- | ----------------------------------------------------- |
| `referrer_customer` | string  | Filter by the referring customer's ID.                |
| `limit`             | integer | Number of results to return. Default `10`, max `100`. |

`GET /v1/referrals`

```bash
curl "https://api.vinr.com/v1/referrals?referrer_customer=cust_8aZ2&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const referrals = await vinr.referrals.list({
referrer_customer: 'cust_8aZ2',
limit: 10,
});
```

```python
import vinr

referrals = vinr.Referral.list(
  referrer_customer="cust_8aZ2",
  limit=10,
)
```

```ruby
referrals = Vinr::Referral.list(
referrer_customer: 'cust_8aZ2',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "ref_2Dm5kW",
    "referrer_customer": "cust_8aZ2",
    "referred_customer": "cust_9bY3",
    "status": "rewarded",
    "reward_amount": 1000,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`referral.created`, `referral.qualified`, and `referral.rewarded`. See [Events](/docs/api-reference/events).