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

# Programs and groups

> How organizations, programs, groups, partners and links fit together, and when to use each.

Your account holds programs. A program holds groups of partners, and each partner shares links and promotion codes.

 Acme Partners prg\_

 VIP grp\_

 Sam Rivera part\_

Shares a link

**link**lnk\_4DwKp9Xm…param"ref"value"sam"urlacme.com/?ref=sam

Shares a code

**promotion\_code**promo\_7RtYw3…code"SAM20"partner\_idpart\_8fKq2LmZ…

Flows live on groups, so the group decides what its partners earn.

## What each level is for

| Level | What it holds | Example |
| - | - | - |
| **Organization** | Your Tolt account: API keys, webhooks, billing | Acme |
| **Program** `prg_` | One affiliate program: currency, cookie window, payout term, minimum payout, partner portal | Acme Partners, USD, 30 days, NET-15 |
| **Group** `grp_` | A segment of partners with its own [flows](/concepts/commission-flows). Exactly one is the default | Default, VIP, Influencers |
| **Partner** `part_` | One affiliate, in one program and one group | Sam Rivera |
| **Link** `lnk_` | A `param` + `value` pair, created with the partner | `acme.com/?ref=sam` |
| **Promotion code** `promo_` | A coupon tied to a partner | `SAM20` |

Customers, transactions and commissions hang off the partner. See [attribution](/concepts/attribution) for how a customer gets bound.

## Programs or groups

New product or currency

**program**prg\_3hTq9WxL…currency\_code"USD"cookie\_duration30payout\_termNET-15subdomain"acme"

Same product, new deal

**group**grp\_9KdLw2Rx…name"VIP"flow40%is\_privatetrueis\_defaultfalse

Most companies run one program and a few groups.

## Common group setups

* **VIP group.** Give the group its own flow at 40% and move top partners into it. Everyone else stays on the default 20%.
* **Private group.** Mark a group private and share its signup link only with influencers you invite. They land in that group with its own rates.
* **Automatic promotion.** A flow with the `change_group` action moves a partner to VIP once they pass, say, 10 paying customers.
* **No-pay group.** A group with no active commission flow earns nothing, as long as no program-wide flow applies. Useful for internal accounts.

For one partner with a special rate, use a [partner override](/concepts/commission-flows#overrides) on the existing flow instead of a new group.

## Move a partner between groups

Programs and groups are read-only in the API. A partner's group is writable:

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

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

await tolt.partners.update({
  id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  group_id: "grp_9VbKt3MwQ7xLr2ZnHy5cDfJp",
});
```

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

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

client.partners.update(
    id="part_8fKq2LmZx7RtYw3nVbHc5dPj",
    group_id="grp_9VbKt3MwQ7xLr2ZnHy5cDfJp",
)
```

```bash cURL theme={"system"}
ID=part_8fKq2LmZx7RtYw3nVbHc5dPj
curl -X PUT "https://platform.tolt.com/v2/partners/$ID" \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "group_id": "grp_9VbKt3MwQ7xLr2ZnHy5cDfJp" }'
```

The new group's flows apply from the partner's next payment. Existing commissions don't change.


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