Managing partner groups

Groups let you segment the partners in a program into tiers — for example a standard tier and a VIP tier — each with its own reward structure. Every program has one Default group where newly approved partners land, and you can add more groups and reassign partners as they grow. Admins and workspace managers use this to run differentiated commission plans without spinning up separate programs.

In the dashboard

Groups live under /<workspace>/groups. The list shows each group, its program, a summary of configured rewards, and the partner count. The default group is marked with a Default badge.

1. ●

   Open the Groups page

   Go to /<workspace>/groups. Note that groups are created automatically when you create a program, so you always start with at least the default one.

2. ●

   Create a new group

   Click New group in the top-right, pick which program it belongs to, and give it a name and optional description. New partners are not placed here automatically — only the default group receives partners on approval.

3. ●

   Set the reward structure

   Open a group and stay on the Rewards tab. There are three reward cards — Sale reward, Lead reward, and Click reward. Click a card to open the editor and press Add reward (or Update reward if one already exists). You can configure:

   • Reward type — Percentage (%) or Flat amount ($). Only sale rewards can be a percentage; lead and click rewards are flat only.
   • Commission interval (sale only) — one_time, recurring, or lifetime. Recurring lets you set a Duration in months (blank means unlimited).
   • Holding period (days) — how long before a commission unlocks, to protect against refunds. Defaults to 30.

   A live Reward preview shows the resulting terms. Use the trash icon next to Update reward to remove a reward entirely.

4. ●

   Move partners between groups

   On a group's Partners tab, each row has a Group dropdown. Pick another group to reassign that partner immediately. The dropdown only lists groups in the same program, and it is disabled when the program has fewer than two groups.

5. ●

   Rename or describe a group

   The Settings tab lets you update the group name and description.

Via the API / for agents

The reward editor and the move-partner control are backed by workspace-scoped REST endpoints. An agent can drive the same actions.

Set (upsert) a group reward

POST /api/workspaces/<slug>/groups/<groupId>/rewards
Content-Type: application/json

{
  "eventType": "sale",            // "sale" | "lead" | "click"
  "rewardType": "percentage",     // "percentage" (sale only) | "flat"
  "rewardAmount": 2000,           // stored ×100: bps for %, cents for $ (2000 = 20% or $20.00)
  "rewardInterval": "one_time",   // "one_time" | "recurring" | "lifetime" (sale only)
  "rewardDurationMonths": null,   // number of months for recurring, else null
  "holdingPeriodDays": 30
}

A single call per event type acts as an upsert — posting again for the same eventType replaces that group's reward.

Remove a group reward

DELETE /api/workspaces/<slug>/groups/<groupId>/rewards
Content-Type: application/json

{ "eventType": "lead" }

Move a partner to another group

PATCH /api/workspaces/<slug>/partners/<partnerId>
Content-Type: application/json

{ "groupId": "<uuid>" }

// 200 OK
{ "ok": true }

The endpoint requires a manage-level role and validates that the target group belongs to the partner's program. A cross-program groupId returns 400 Group not found in this partner's program.

Gotchas