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

# Approve commissions

> Decide when commissions become payable: immediately, after a refund window, or by hand.

Only approved commissions are paid out. You choose how a commission gets there: right away, after a delay, or by hand.

comm\_7Lq3NzVx… Sam Rivera · Manual approvalCreated\$14.70 PendingOct 2ApprovedPOST …/approve ApprovedOct 4DeclinedPOST …/decline RejectedOct 4Refundedamount: 0 RefundedOct 4PaidNET-15 payout PaidOct 30

## Pick an approval mode

Approval is an option on each commission flow, set in the dashboard. Different groups can use different modes.

Default

**immediate**statusapprovedapprovesat once

Refund window

**delay**1 to 999dstatuspendingapproves+30d

Your review

**manual**statuspendingapproves…/approve

Delayed commissions carry a `scheduled_approval_date`. A refund before that date moves the commission to `refunded`, so it never pays.

## Review pending commissions

List what is waiting, then approve or decline one at a time.

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

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

const { data: pending } = await tolt.commissions.list({
  status: "pending",
  limit: 50,
});

await tolt.commissions.approve({ id: "comm_7Lq3NzVx8KtRb2WcYm5pHd4j" });
await tolt.commissions.decline({ id: "comm_4Hs9PwQz1MvXc6TbLn8rKe2g" });
```

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

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

pending = client.commissions.list(status="pending", limit=50).items

client.commissions.approve(id="comm_7Lq3NzVx8KtRb2WcYm5pHd4j")
client.commissions.decline(id="comm_4Hs9PwQz1MvXc6TbLn8rKe2g")
```

```bash cURL theme={"system"}
curl -G https://platform.tolt.com/v2/commissions \
  -d status=pending \
  -d limit=50 \
  -H "Authorization: Bearer $TOLT_API_KEY"

ID=comm_7Lq3NzVx8KtRb2WcYm5pHd4j
curl -X POST \
  "https://platform.tolt.com/v2/commissions/$ID/approve" \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

For batches, `POST /v2/commissions/bulk/approve` and `/bulk/decline` take up to 100 `ids`. Each id is handled on its own; read `failed` and the per-id `code` in the result. The batch is written in one transaction, so a server error applies none of it and the whole call is safe to retry. Each change fires a `commission.updated` webhook.

| Per-id code | Meaning |
| - | - |
| `commission_paid` | Already paid out. Paid commissions are locked. |
| `commission_frozen` | Tied to a refund or a confirmed invoice. |
| `not_found` | No commission with that id in your organization. |

## Recipe: approve after 30 days

Running manual approval but want the delay behavior with your own checks? Approve every commission still pending after 30 days. Refunded commissions have already left `pending`, so whatever remains is clean.

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

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });
const cutoff = new Date(
  Date.now() - 30 * 24 * 60 * 60 * 1000,
).toISOString();

let page = await tolt.commissions.list({
  status: "pending",
  created_before: cutoff,
  limit: 100,
});
while (true) {
  const ids = page.data.map((c) => c.id);
  if (ids.length > 0) {
    const { data } = await tolt.commissions.bulkApprove({ ids });
    console.log(`approved ${data.succeeded}, skipped ${data.failed}`);
  }
  if (!page.hasNextPage()) break;
  page = await page.getNextPage();
}
```

```python Python theme={"system"}
import os
from datetime import datetime, timedelta, timezone
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])
cutoff = datetime.now(timezone.utc) - timedelta(days=30)

pages = client.commissions.list(
    status="pending", created_before=cutoff, limit=100
).iter_pages()
for page in pages:
    ids = [c.id for c in page.items or []]
    if ids:
        result = client.commissions.bulk_approve(ids=ids).data
        print(f"approved {result.succeeded}, skipped {result.failed}")
```

Run it daily from a cron job. Approving items does not break the cursor: it stays a valid position after the commission leaves `pending`.


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