Partner Groups
Define classification tiers for partners and manage automated rules for commissions and performance-based incentives.
Partner Groups API
Partner Groups provide an automated logic layer for categorizing partners and enforcing organization-wide distribution policies. These groups define rules that govern revenue sharing percentages, time-based commission tiers, and performance-driven upgrades based on total Lifetime Value (LTV) or charge volume.
Group Inventory
List Partner Groups
Retrieve a paginated directory of all defined Partner Groups. This directory contains the high-level metadata and administrative identifiers for each group.
partner_groups:readApiAccessPermission::PARTNER_GROUPS_READQuery Parameters
sizeintegerpageintegerResponses
Partner group directory successfully retrieved.
{
"entities": "PartnerGroup",
"count": 4,
"per_page": 100,
"pages": {
"current": 1,
"max": 1
},
"elements": [
{
"id": "68f76721...",
"name": "Standard Managed Agency",
"external_id": "P-GROUP-ADVANCED",
"default": true
}
]
}Retrieve Group Configuration & Rules
Fetch the comprehensive configuration for a specific governance group, including the active rules engine parameters that define commission logic.
partner_groups:readApiAccessPermission::PARTNER_GROUPS_READQuery Parameters
groupIdstringRequiredResponses
Group configuration and rules engine definition retrieved.
{
"id": "68f76721...",
"name": "Standard Managed Agency",
"external_id": "P-GROUP-ADVANCED",
"rules": [
{
"type": "new_customer_time_tier",
"max_months": 12,
"percentage": 50,
"description": "Introductory 12-month high-incentive tier."
},
{
"type": "recurring",
"percentage": 15,
"description": "Standard recurring commission (post-time-tier)."
},
{
"type": "partner_ltv_upgrade",
"min_ltv_total": 10000,
"upgrade_percentage": 5,
"description": "LTV Performance Bonus (Threshold: 10,000€)."
}
],
"tags": "managed,high-volume",
"description": "Default group for high-performance managed agencies."
}Group Lifecycle Management
Create Partner Group
partner_groups:writeApiAccessPermission::PARTNER_GROUPS_WRITEQuery Parameters
No query parameters required.
Request Body
{
"partnerGroup": {
"name": "Performance Agencies",
"description": "Tier for high-volume agencies",
"external_id": "P-GROUP-PERF",
"tags": "managed,performance",
"default": false,
"rules": [
{
"type": "new_customer_time_tier",
"max_months": 6,
"percentage": 30
},
{
"type": "recurring",
"percentage": 12
}
]
}
}partnerGroup.namestringRequiredpartnerGroup.rulesarrayRequiredpartnerGroup.descriptionstringpartnerGroup.external_idstringpartnerGroup.tagsstringpartnerGroup.defaultbooleanResponses
Partner group created.
{
"group": {
"id": "68f76721..."
}
}Update Partner Group
partner_groups:writeApiAccessPermission::PARTNER_GROUPS_WRITEQuery Parameters
partnerGroupIdstringRequiredRequest Body
{
"partnerGroup": {
"name": "Performance Agencies v2",
"default": true,
"rules": [
{
"type": "recurring",
"percentage": 14
}
]
}
}partnerGroup.namestringpartnerGroup.descriptionstringpartnerGroup.external_idstringpartnerGroup.tagsstringpartnerGroup.defaultbooleanpartnerGroup.rulesarrayResponses
Partner group updated.
{
"group": {
"id": "68f76721..."
}
}Delete Partner Group
partner_groups:writeApiAccessPermission::PARTNER_GROUPS_WRITEQuery Parameters
partnerGroupIdstringRequiredResponses
Partner group deleted.
{
"group": {
"id": "68f76721...",
"deleted": true
}
}Simulate Rules
partner_groups:writeApiAccessPermission::PARTNER_GROUPS_WRITEQuery Parameters
No query parameters required.
Request Body
{
"partnerGroupSimulation": {
"rules": [
{
"type": "new_customer_time_tier",
"max_months": 3,
"percentage": 25
},
{
"type": "recurring",
"percentage": 10
}
],
"simulation": {
"charge_amount": 299.9,
"customer_months": 2,
"partner_ltv": 4500,
"qualified_customers": 12,
"first_paid_customer_bootstrap": false
}
}
}partnerGroupSimulation.rulesarrayRequiredpartnerGroupSimulation.simulationobjectRequiredResponses
Rules simulation completed.
{
"status": "success",
"result": {
"final_fee": 74.98
}
}The Rules Engine
Partner groups are powered by a deterministic rules engine that evaluates transactions in real-time. The following rule types are supported:
Rule Type Definitions
| Rule Type | Description | Key Parameters |
|---|---|---|
new_customer_time_tier | Applies a specific commission for the initial months of a customer's lifecycle. | max_months, percentage |
recurring | The baseline commission applied to all transactions when no other specific rule applies. | percentage |
partner_ltv_upgrade | Triggers a commission percentage increase once a partner's total managed LTV exceeds a threshold. | min_ltv_total, upgrade_percentage |
charge_threshold_bonus | Provides a one-time bonus for transactions exceeding a specific amount. | min_charge_total, bonus |
Evaluation Hierarchy: Rules are evaluated based on the customer's acquisition date and the partner's historical performance. A recurring rule is required for all groups as a fallback mechanism.