> ## 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.

# Payouts & Billing

> How affiliate payouts work and how AgentRef billing and plan limits are managed.

## How Payouts Work

When affiliates earn commissions, the money flows through a simple lifecycle:

```
Conversion Created → Commission Pending → Payout Created → Payout Processing → Payout Completed
```

### Payout Lifecycle

| Status       | Description                                          |
| ------------ | ---------------------------------------------------- |
| `pending`    | Commission earned, waiting to reach payout threshold |
| `processing` | Merchant has started the external payment step       |
| `completed`  | Merchant marked the payout as paid                   |
| `failed`     | External payment attempt failed and can be retried   |

### Payout Thresholds

Affiliates become payout-eligible when approved commissions reach the threshold. You then create the manual payout record in AgentRef. Default threshold: **\$50 USD**. Configurable per program.

### Manual payout workflow

This is the active launch contract for payouts today.

Affiliates save payout details in AgentRef using PayPal or bank transfer fields. Merchants then:

1. Create a payout record in AgentRef
2. Export or prepare the payout externally
3. Send the payment outside AgentRef
4. Mark the payout as `processing`, `completed`, or `failed`

AgentRef tracks the payout state and audit trail, but does not move money on the merchant's behalf.

<Info>
  REST and SDKs can list pending affiliates, create payout records, list payout history, and read payout stats. Marking payout status, listing upcoming payouts, and exporting payout CSV files are currently available through Merchant MCP and the dashboard workflow.
</Info>

## Managing Payouts via API

### List Payouts

<CodeGroup>
  ```javascript Node.js theme={null}
  const payouts = await client.payouts.list({
    programId: 'prg_abc123',
    status: 'pending',
  })
  ```

  ```python Python theme={null}
  payouts = client.payouts.list(
      program_id="prg_abc123",
      status="pending",
  )
  ```

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

### List Pending Affiliates

<CodeGroup>
  ```javascript Node.js theme={null}
  const pending = await client.payouts.listPending({
    programId: 'PROGRAM_ID',
  })
  ```

  ```python Python theme={null}
  pending = client.payouts.list_pending(program_id="PROGRAM_ID")
  ```

  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/payouts/pending?programId=PROGRAM_ID" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```
</CodeGroup>

### Create a Payout Record

<CodeGroup>
  ```javascript Node.js theme={null}
  const payout = await client.payouts.create({
    affiliateId: 'AFFILIATE_ID',
    programId: 'PROGRAM_ID',
    method: 'paypal',
    notes: 'April payout',
  }, {
    idempotencyKey: 'payout-affiliate-april',
  })
  ```

  ```python Python theme={null}
  payout = client.payouts.create(
      affiliate_id="AFFILIATE_ID",
      program_id="PROGRAM_ID",
      method="paypal",
      notes="April payout",
      idempotency_key="payout-affiliate-april",
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://www.agentref.co/api/v1/payouts" \
    -H "Authorization: Bearer ak_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: payout-affiliate-april" \
    -d '{
      "affiliateId": "AFFILIATE_ID",
      "programId": "PROGRAM_ID",
      "notes": "April payout"
    }'
  ```
</CodeGroup>

### Payout Statistics

<CodeGroup>
  ```javascript Node.js theme={null}
  const stats = await client.payouts.stats({
    programId: 'prg_abc123',
  })
  // { totalPaid, totalPending, totalFailed, count }
  ```

  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/payouts/stats?programId=prg_abc123" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```
</CodeGroup>

***

## AgentRef Billing

AgentRef starts with a free tier and supports paid Starter, Growth, and Pro plans. Billing is managed from the dashboard and through the Billing API.

### How It Works

* **\$0 to start** – no upfront cost, no credit card required
* **Upgrade when you need higher limits** – paid plans unlock more storage, notifications, and operating room
* **No automatic downgrade** – plan changes are merchant-initiated

### Billing API

<CodeGroup>
  ```javascript Node.js theme={null}
  // View current billing status
  const billing = await client.billing.current()

  // View available tiers
  const tiers = await client.billing.tiers()
  ```

  ```bash cURL theme={null}
  # View billing status
  curl "https://www.agentref.co/api/v1/billing" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"

  # View tiers
  curl "https://www.agentref.co/api/v1/billing/tiers" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```
</CodeGroup>

<Info>
  Billing is handled automatically through Stripe. You can view your usage and invoices in the AgentRef dashboard under **Settings → Billing**.
</Info>