Partner Entity
Understanding the Partner ecosystem, group associations, and customer attribution.
Partner Entity
A Partner represents an external agency, reseller, or affiliate that manages its own pool of customers. Partners are categorized into Groups for tiered commission management and service segmentation.
Usage
The Partner entity is used to:
- Segment your customer base by agency or reseller.
- Manage commission structures and payout history.
- Distribute reporting and management capabilities to third parties.
Expected Lifecycle Flow
Follow this logical flow to establish a partner-based reseller model:
Define Tiers & Groups
Use POST /partners/groups.json to categorize partners. This allows you to apply different commission rules or API access levels to different types of resellers.
Partner Onboarding
Initialize the partner identity via POST /partners.json. Associate them with a group_id and provide their legal and tax information.
Customer Attribution
When onboarding a new customer through your platform, include the partner.id in the creation payload. DonutWork will automatically attribute future revenue to this partner.
Performance & Payouts
Monitor real-time performance via GET /partners/{id}/stats.json and manage revenue sharing through the payouts.json endpoints.
Partner Introductions
Set referrer_partner_id when creating a partner, or once later with PUT /partners/{partnerId}.json. The relationship must remain within the company, cannot form a cycle, and cannot be replaced after assignment. The partner still receives direct commissions from customers they bring in.
Configure the separate company policy with GET and PUT /partners/referral-policy.json (partner_groups:read and partner_groups:write). The default is disabled. After a direct commission is assigned, upstream commissions are calculated asynchronously from the preceding fee, within the configured depth and overall cap. These fees are visible in the partner fee ledger and use the normal payout flow. No subscription check applies.
Data Schema
The core fields defining a Partner object:
| Field | Type | Description |
|---|---|---|
id | eid | Unique extended identifier. |
name | string | Legal company name of the partner. |
email | string | Main contact and billing address. |
group_id | string | The ID of the assigned classification group. |
referrer_partner_id | `string | null` |
external_id | string | Your internal system reference. |
tags | array | Arbitrary labels for custom filtering (e.g., 'gold', 'reseller'). |
Relationship Call Graph
How Partners interact with the customer onboarding flow: