> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversions

> Understand the conversion lifecycle, how Stripe events create conversions, and how to query and aggregate your conversion data.

A conversion is created every time an affiliate-referred customer completes a purchase. It records the sale amount, the commission owed, and the current status of that commission. Conversions are the backbone of your affiliate program – everything from payouts to fraud detection is tied to them.

## Conversion lifecycle

```
pending → approved → paid
   ↓          ↓
rejected  partially_refunded → refunded
```

| Status               | What it means                                                                  |
| -------------------- | ------------------------------------------------------------------------------ |
| `pending`            | Conversion created from a Stripe event. Waiting for review or approval window. |
| `approved`           | Commission confirmed. Will be included in the next payout.                     |
| `partially_refunded` | Part of the Stripe charge was refunded. Commission is reduced proportionally.  |
| `refunded`           | The underlying Stripe charge was fully refunded. Commission is voided.         |
| `rejected`           | Manually rejected or flagged as fraudulent. Commission is voided.              |

<Info>
  Most programs approve conversions automatically. If your program has fraud detection enabled, suspicious conversions may stay in `pending` until you resolve the associated flag.
</Info>

## How conversions are created

AgentRef listens to your connected Stripe account for `checkout.session.completed` and `invoice.payment_succeeded` events. When a purchase is traced back to an affiliate click (via cookie or referral code), a conversion is created automatically – no server-side code needed beyond the tracking snippet.

The conversion captures:

* `amount` – the charged amount in cents
* `currency` – from the Stripe charge
* `customerEmail` – from the Stripe customer
* `commission` – calculated from your program's `commissionPercent`
* `commissionType` – `one_time` or `recurring` / `recurring_limited`

## Viewing conversions in the dashboard

Go to **Programs > \[Your Program] > Conversions**. You can filter by status, date range, or affiliate. Click any row to see the full conversion detail including the originating click and Stripe charge ID.

## API reference

### List conversions

Scope: `conversions:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/conversions?status=pending&limit=25" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  import { AgentRef } from 'agentref';

  const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' });

  const { data, meta } = await client.conversions.list({
    status: 'pending',
    limit: 25,
  });

  for (const conversion of data) {
    console.log(conversion.id, conversion.amount, conversion.status);
  }
  ```

  ```python Python theme={null}
  from agentref import AgentRef

  client = AgentRef(api_key='ak_live_YOUR_KEY')

  result = client.conversions.list(status='pending', limit=25)

  for conversion in result.data:
      print(conversion.id, conversion.sale_amount, conversion.status)
  ```
</CodeGroup>

**Query parameters**

| Parameter            | Type         | Description                                                                 |
| -------------------- | ------------ | --------------------------------------------------------------------------- |
| `programId`          | UUID         | Filter to a specific program                                                |
| `affiliateId`        | UUID         | Filter to a specific affiliate                                              |
| `status`             | string       | `pending` \| `approved` \| `partially_refunded` \| `rejected` \| `refunded` |
| `startDate` / `from` | ISO datetime | Start of date range                                                         |
| `endDate` / `to`     | ISO datetime | End of date range                                                           |
| `limit`              | number       | Max results (1–100)                                                         |
| `page` / `offset`    | number       | Pagination                                                                  |

### Get conversion stats

Returns aggregate metrics for a time period. Scope: `stats:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/conversions/stats?period=30d&programId=PROGRAM_ID" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  const stats = await client.conversions.stats({
    period: '30d',
    programId: 'PROGRAM_ID',
  });

  console.log(stats.total);
  console.log(stats.totalRevenue);   // in cents
  console.log(stats.totalCommissions);
  ```

  ```python Python theme={null}
  stats = client.conversions.stats(period='30d', program_id='PROGRAM_ID')

  print(stats.total)
  print(stats.total_revenue)    # in cents
  print(stats.total_commissions)
  ```
</CodeGroup>

**Period options:** `7d`, `30d`, `90d`, `all`

### Get recent conversions

Returns the most recent conversions (up to 20). Useful for dashboard widgets and webhooks verification. Scope: `conversions:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/conversions/recent?limit=5" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  const recent = await client.conversions.recent({ limit: 5 });
  ```

  ```python Python theme={null}
  recent = client.conversions.recent(limit=5)
  ```
</CodeGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Payouts & Billing" href="/merchant-guide/payouts-billing">
    Learn how approved conversions become payouts to your affiliates.
  </Card>

  <Card title="Fraud Detection" href="/merchant-guide/fraud-detection">
    See how AgentRef flags suspicious conversions before they're approved.
  </Card>
</CardGroup>