API reference
Affiliates
List, invite, and update the partners in a program.
List affiliates
GET
/v1/programs/:programId/affiliatesread scopeLists affiliates with search, status filtering, and pagination. Each row carries lifetime click, conversion, and commission totals.
Path parameters
| programIdrequuid | From `GET /v1/me`. |
Query parameters
| statusenum | `pending` · `active` · `suspended` · `rejected` · `archived` |
| searchstring | Matches name, email, or referral code. |
| limitint | 1–200. Defaults to 50. |
| offsetint | Defaults to 0. |
Response
json
{
"affiliates": [
{
"id": "c41a...",
"firstName": "Kristin",
"lastName": "Richards",
"email": "kristin@example.com",
"referralCode": "a8f2k1x9",
"vanitySlug": "kristin",
"status": "active",
"groupId": "11bc...",
"parentAffiliateId": null,
"createdAt": "2026-08-01T10:04:00Z",
"clicks": 1284,
"conversions": 37,
"commissionCents": 184200
}
],
"total": 213,
"limit": 50,
"offset": 0
}- Tax information and payout account identifiers are never returned — `tax_info` holds an encrypted TIN and no integration needs it.
Invite an affiliate
POST
/v1/programs/:programId/affiliateswrite scopeCreates an affiliate without an auth user. They claim the account by signing up with the same email address.
Path parameters
| programIdrequuid | From `GET /v1/me`. |
Body parameters
| emailreqstring | Must be unique per program. |
| firstNamereqstring | |
| lastNamereqstring | |
| groupIduuid | Commission tier. Must belong to this program. |
| parentAffiliateIduuid | Upline for 2-tier commissions. Must belong to this program. |
| autoApproveboolean | Skip the pending queue. Defaults to `false`. |
| sendInviteboolean | Email an invitation. Defaults to `true`. |
Response
json
{
"id": "c41a...",
"email": "kristin@example.com",
"referralCode": "a8f2k1x9",
"status": "pending"
}- Returns `409` if an affiliate with that email already exists in the program.
Update an affiliate
PATCH
/v1/programs/:programId/affiliates/:idwrite scopeUpdates status, commission override, tier, upline, or vanity slug. Omitted fields are untouched; `null` clears a nullable field.
Path parameters
| programIdrequuid | From `GET /v1/me`. |
| idrequuid | The affiliate to update. |
Body parameters
| statusenum | Setting `active` approves the affiliate and emails them. |
| groupIduuid | null | |
| parentAffiliateIduuid | null | |
| commissionOverrideType'percentage' | 'flat' | null | |
| commissionOverrideRatenumber | null | |
| vanitySlugstring | null | Custom short-link slug. |
Response
json
{
"id": "c41a...",
"status": "active",
"groupId": "11bc...",
"parentAffiliateId": null,
"vanitySlug": "kristin",
"commissionOverrideType": null,
"commissionOverrideRate": null
}- `commissionOverrideType` and `commissionOverrideRate` must be sent together — a rate with no type reads as absent and would silently do nothing.
- A per-affiliate override does **not** beat a per-product commission rule. See Commission resolution.