Commission lifecycle

A flow 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 delay

Created PendingDay 0

DeclinedPOST …/decline RejectedDay 3

Refundedamount: 0 RefundedDay 9

Approveddelay ends ApprovedDay 30

Paidpayout_id set PaidDay 45

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

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

programprg_3hTq9WxL…

payout_termNET-15

minimum_payout5000

Sam’s payout

payoutOct 1 to 15

commissions4 approved

total5880

methodpaypal

statuspaid

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

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) });
}

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])

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 to react to approvals (including delayed auto-approvals), declines and edits. A refund through POST /v2/transactions/{id}/refund sends only transaction.updated, so when you get one, refetch that transaction’s commissions with GET /v2/commissions?transaction_id=....

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

Commission lifecycle

What moves each step

Refunds

Payouts

Track it with the API

​What moves each step

​Refunds

​Payouts

​Track it with the API

What moves each step

Refunds

Payouts

Track it with the API