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

> Rules that decide what partners earn: when something happens, if conditions match, pay this much.

A flow is one rule on a group: **when** an event happens, **if** its conditions match, **pay** a commission. You build flows in the dashboard; the API reads them.

Flow on VIP

**flow**VIPeventtransaction\_createdifconverted ≤ 365d agopay30%approvaldelay 30d

On a \$49.00 payment

**commission**comm\_7XqLm2Kw…partner"sam"amount1470statuspendingscheduled\_approval\_date+30d

One flow on the VIP group: 30% of every payment in the customer's first year.

Every program starts with a **Default Flow** on its default group. Each group has its own flows, so moving a partner to another [group](/concepts/programs-groups) changes what they earn. A flow with no group applies to every partner in the program, and when a click's link belongs to a campaign, the campaign's flows run instead of the group's.

## Triggers

| Trigger | Event | Runs |
| - | - | - |
| **New payment** | `transaction_created` | On every payment from a referred customer, renewals included |
| **New signup** | `lead_created` | Once, when a referred customer signs up. Fixed amounts only |

Refunds and updates never trigger flows.

## Conditions

No conditions means the flow runs on every event. Otherwise combine conditions in AND / OR groups, up to three levels deep.

| Category | Conditions |
| - | - |
| **Payment** (New payment only) | amount, billing type, interval, product ID, product quantity, promotion code (billing-integration payments only) |
| **Customer** | number of transactions, total paid, identifier, created date, conversion date |
| **Partner** | number of transactions, customers or leads, partner ID, total revenue, total earnings, earned per customer, signup date, country, link |

Conditions are checked when the event is processed. "Conversion date is within 350 days" means the customer first paid less than 350 days ago.

## Actions

* **Pay a commission.** A percentage of the payment (up to 500%) or a fixed amount per event.
* **Move the partner to another group.** Pays nothing; the new group's flows apply from the next event.

### Overrides

Give one partner or one link a different rate on the same flow, without a second flow.

1\. Link override

**link**lnk\_4DwKp9…value"sam-yt"rate10%

2\. Partner override

**partner**part\_8fKq…nameSam Riverarate40%

3\. Flow

**flow**VIP groupscopeall partnersrate30%

The first one that applies wins.

## Approval

| Option | Commission starts as | Use it for |
| - | - | - |
| **Immediate** (default) | `approved` | Low refund risk |
| **Delay** (1 to 999 days) | `pending`, approved automatically after the delay | Covering a refund window |
| **Manual** | `pending` until someone approves it | Reviewing every sale |

> **More options: yearly proration and product limits**
>
> **Prorate yearly payments** splits a yearly payment's commission into equal monthly parts over 3, 6 or 12 months. **Limit commissions per product** caps how many commissions a partner earns from the flow per product ID.

## Every matching flow runs

There is no priority and no "stop at first match". Every active flow that applies to the partner and whose conditions match pays: their group's flows plus program-wide ones (or the campaign's, for campaign links).

> [!WARNING]
>
> Two overlapping flows pay twice for the same payment. Use an override for one partner, or make conditions mutually exclusive (for example "within 350 days" and "after 350 days").

Editing, pausing or deleting a flow never changes existing commissions. To apply flows to a past payment, call `POST /v2/transactions/{id}/rerun-flows`. It returns `409 commission_exists` when the payment already has a commission, and `409 transaction_refunded` when it was refunded.

## Recipes

> **Flat 30% recurring**
>
> New payment · no conditions · 30%. The most common setup.

> **30% for the first 12 months**
>
> New payment · conversion date within 350 days · 30%. The cutoff sits between renewals 12 and 13.

> **\$20 per signup**
>
> New signup · no conditions · fixed 20.

> **VIP group at 40%**
>
> A flow on the VIP group at 40%, next to the default group's 20%.

> **30-day hold**
>
> Any flow with approval set to delay, 30 days. Refunds inside the hold never reach a payout.

> **First payment only**
>
> New payment · customer number of transactions equals 1 · 30%.

## Read flows with the API

Flows are read-only in the API: `GET /v2/flows` and `GET /v2/flows/{id}`.

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

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });
const { data } = await tolt.flows.list({
  group_id: "grp_6JmRw2KxQ9tLbZ4nVhYc8FsD",
  active: true,
});
```

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

client = ToltApi(token=os.environ["TOLT_API_KEY"])
page = client.flows.list(
    group_id="grp_6JmRw2KxQ9tLbZ4nVhYc8FsD", active=True
)
```

```bash cURL theme={"system"}
curl -G https://platform.tolt.com/v2/flows \
  -d group_id=grp_6JmRw2KxQ9tLbZ4nVhYc8FsD \
  -d active=true \
  -H "Authorization: Bearer $TOLT_API_KEY"
```


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