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

# Commission lifecycle

> How a commission moves from pending to paid, what refunds do, and when partners get paid out.

A [flow](/concepts/commission-flows) creates a commission when a referred customer pays. It then moves toward a payout, or drops out when you decline it or the payment is refunded.

comm\_7XqLm2Kw… Sam Rivera · 30-day delayCreated\$14.70 PendingDay 0DeclinedPOST …/decline RejectedDay 3Refundedamount: 0 RefundedDay 9Approveddelay ends ApprovedDay 30Paidpayout\_id set PaidDay 45Refund-\$14.70 RefundDay 60

## What moves each step

| Step | What causes it |
| - | - |
| created as `pending` | A flow with delayed or manual approval |
| created as `approved` | A flow with immediate approval (the default), or `POST /v2/commissions` (defaults to `approved`) |
| `pending` to `approved` | The approval delay passes (`scheduled_approval_date`), or you approve it in the dashboard or with `POST /v2/commissions/{id}/approve` |
| to `rejected` | You decline it (dashboard or `POST /v2/commissions/{id}/decline`), or the program's fraud settings reject it |
| `approved` to `paid` | The commission is included in a payout that is paid |
| to `refunded` | The transaction is refunded before the commission is paid. Its amount becomes 0 |

Paid commissions are locked: approving, declining, updating or deleting one returns `commission_paid`. Bulk versions take up to 100 ids: `POST /v2/commissions/bulk/approve` and `/bulk/decline`.

## Refunds

Refund a payment in your billing system (integrations pick it up) or with `POST /v2/transactions/{id}/refund`. An unpaid commission becomes `refunded` with amount 0. A paid one is never edited: Tolt adds a negative commission (`type: refund`, `approved`) that is deducted from the partner's next payout.

> [!TIP]
>
> A 30-day approval delay keeps commissions `pending` through your refund window, so refunded sales never reach a payout.

## Payouts

A payout groups a partner's approved commissions for one payout term. It is paid once the total reaches the program's minimum payout and the partner has a payout method connected.

Program rules

**program**prg\_3hTq9WxL…payout\_termNET-15minimum\_payout5000

Sam's payout

**payout**Oct 1 to 15commissions4 approvedtotal5880methodpaypalstatuspaid

* **Methods:** PayPal, Wise, bank transfer, wire and crypto. Partners connect theirs in the partner portal.
* **Funding:** you pay an invoice for the payout run (card or US bank account), or turn on autopayouts.
* **Statuses:** `pending`, `not_eligible`, `processing`, `paid`, `failed`.

Payouts are managed in the [dashboard](/dashboard/payouts). The API has no payout endpoints, but each paid commission carries its `payout_id`.

## Track it with the API

List what's waiting for review and approve it in one call:

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data } = await tolt.commissions.list({
  status: "pending",
  limit: 100,
});
if (data.length > 0) {
  await tolt.commissions.bulkApprove({ ids: data.map((c) => c.id) });
}
```

```python Python theme={"system"}
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

page = client.commissions.list(status="pending", limit=100)
if page.items:
    client.commissions.bulk_approve(ids=[c.id for c in page.items])
```

```bash cURL theme={"system"}
curl -X POST \
  "https://platform.tolt.com/v2/commissions/bulk/approve" \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["comm_7XqLm2KwR9tZb4NvHc8YdFsJ"] }'
```

Subscribe to [`commission.updated`](/webhooks/events/commission-updated) to react to approvals (including delayed auto-approvals), declines and edits. A refund through `POST /v2/transactions/{id}/refund` sends only [`transaction.updated`](/webhooks/events/transaction-updated), so when you get one, refetch that transaction's commissions with `GET /v2/commissions?transaction_id=...`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.