Partners
Manage partner channels, commission settlement cycles, and partner-customer associations.
Partners API
The Partners API enables organizations to build and scale distribution networks through agencies, resellers, and affiliates. It provides a framework for managing partner identities, commission calculations (fees), and financial settlements (payouts), while maintaining clear attribution for every customer acquired through the channel.
Channel Management
List Partners
Retrieve a paginated directory of all registered partners. This list includes high-level identification data and current status for each collaborative entity.
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
sizeintegerpageintegerResponses
Partner directory successfully retrieved.
{
"entities": "Partner",
"count": 24,
"per_page": 100,
"pages": {
"current": 1,
"max": 1
},
"elements": [
{
"id": "675d...",
"name": "Global Solutions Agency",
"external_id": "GSA-9921",
"partner_code": "GOLD-PARTNER-X"
}
]
}Provision New Partner
Onboard a new partner into the ecosystem. This initializes their profile and associates them with a governance group (Partner Group) to define their commission rules.
partners:writeApiAccessPermission::PARTNERS_WRITEQuery Parameters
No query parameters required.
Request Body
{
"partner": {
"name": "Apex Marketing Group",
"email": "channel@apex-marketing.com",
"external_id": "APEX_001",
"code": "APEXPROMO",
"partner_group_id": "66bf22b0...",
"address": {
"vat_number": "IT09876543210",
"country": "IT",
"city": "Milan"
}
}
}partner.namestringRequiredpartner.emailstringRequiredpartner.partner_group_idstringpartner.address.countrystringRequiredResponses
Partner successfully provisioned.
{
"partner": {
"id": "6768..."
}
}Retrieve Partner Profile
Fetch the comprehensive profile of a specific partner, including their fee structure, whitelist configuration, and association metadata.
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
partnerIdstringRequiredResponses
Partner profile retrieved.
{
"id": "66b136b9...",
"name": "Apex Marketing Group",
"status": "active",
"tags": [
"tier-1",
"mfa-enabled"
],
"email": "channel@apex-marketing.com",
"address": {
"city": "Milan",
"country": "IT",
"vat_number": "IT098..."
}
}Attribution & Performance
Audit Attributed Customers
Retrieve a paginated list of all customers currently attributed to a specific partner. This is used to verify channel performance and revenue attribution.
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
partnerIdstringRequiredResponses
Attributed customer list retrieved.
{
"entities": "PartnerCustomers",
"count": 142,
"elements": [
{
"id": "68d2...",
"company_name": "Acme Corp",
"email": "procurement@acme.com",
"status": "active"
}
]
}Performance Analytics
Retrieve high-level performance metrics for a partner, including total attributed revenue and cumulative commissions earned.
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
partnerIdstringRequiredResponses
Aggregated performance statistics retrieved.
{
"total_revenue": "45200.00",
"commission_earned": "4520.00",
"currency": "EUR"
}Financial Settlement (Payouts)
Audit Commission Ledger (Fees)
Retrieve individual commission entries (fees) generated by attributed customer transactions. These entries serve as the basis for payout generation.
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
partnerIdstringRequiredResponses
Commission ledger retrieved.
{
"entities": "PartnerFees",
"elements": [
{
"id": "fee_991",
"source_charge": "ch_123",
"fee_value": 15.5,
"status": "pending"
}
]
}Generate Payout Request
Consolidate multiple 'pending' commission fees into a single Payout request. This initiates the financial settlement cycle and generates a draft settlement record.
partner_payouts:writeApiAccessPermission::PARTNER_PAYOUTS_WRITEQuery Parameters
No query parameters required.
Request Body
{
"payout": {
"partner_id": "675d...",
"transactions": [
"fee_991",
"fee_992"
],
"invoice": {
"number": "INV-2026-001",
"date": "2026-03-01"
},
"vat_settings": {
"tax_id": "tax_vat_22"
}
}
}payout.partner_idstringRequiredpayout.transactionsarrayRequiredpayout.invoice.numberstringRequiredResponses
Payout request successfully generated.
{
"id": "pay_5521",
"total": "1250.00"
}Retrieve Payout Documentation (PDF)
Retrieve a base64-encoded PDF report (Account Statement) for a specific payout. This document serves as the official settlement record for the partner.
partner_payouts:readApiAccessPermission::PARTNER_PAYOUTS_READQuery Parameters
partnerIdstringRequiredpayoutIdstringRequiredResponses
PDF documentation retrieved.
{
"stream": {
"type": "application/pdf",
"base64_content": "JVBER..."
}
}Technical Implementation (Payout Flow)
const payoutData = {
payout: {
partner_id: "PARTNER_6621",
transactions: ["FEE_001", "FEE_002"],
invoice: { number: "REF-9921", date: "2026-03-03" },
vat_settings: { tax_id: "VAT_22_IT" }
}
};
try {
const settlement = await sdk.partners.createPayout(payoutData);
console.log(`Settlement Processed. ID: ${settlement.id}, Total: ${settlement.total}`);
} catch (error) {
console.error(`Settlement Failed: ${error.message}`);
}Additional Partner Operations
Search Partner by External ID or Email
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
externalIdstringemailstringResponses
Partner record retrieved.
{
"id": "675d...",
"name": "Apex Marketing Group",
"email": "channel@apex-marketing.com"
}Neither `externalId` nor `email` was provided.
{
"error": "A valid \"externalId\" or \"email\" must be specified in the request"
}Update Partner Profile
partners:writeApiAccessPermission::PARTNERS_WRITEQuery Parameters
partnerIdstringRequiredRequest Body
{
"partner": {
"name": "Apex Marketing Group - Enterprise",
"email": "enterprise@apex-marketing.com",
"description": "Updated profile",
"external_id": "APEX_001",
"code": "APEXPROMO",
"partner_group_id": "66bf22b0...",
"tags": [
"tier-1",
"priority"
],
"address": {
"country": "IT",
"city": "Milan"
}
}
}partner.namestringpartner.emailstringpartner.descriptionstringpartner.external_idstringpartner.codestringpartner.partner_group_idstringpartner.tagsarray|stringpartner.addressobjectResponses
Partner updated.
{
"id": "675d...",
"name": "Apex Marketing Group - Enterprise"
}Delete Partner
partners:writeApiAccessPermission::PARTNERS_WRITEQuery Parameters
partnerIdstringRequiredResponses
Partner deleted.
{
"id": "675d...",
"deleted": true
}Partner has still attached customers.
{
"error": "Unable to remove this partner. Customer attached to partner: ..."
}Get Partner Fee by ID
partners:readApiAccessPermission::PARTNERS_READQuery Parameters
partnerIdstringRequiredfeeIdstringRequiredResponses
Partner fee entry retrieved.
{
"id": "fee_991",
"partner_id": "675d...",
"fee_value": 15.5,
"status": "pending"
}List Global Payouts
partner_payouts:readApiAccessPermission::PARTNER_PAYOUTS_READQuery Parameters
sizeintegerpageintegerResponses
Paginated payout list across all partners.
{
"entities": "PartnerPayout",
"count": 3,
"elements": []
}List Payouts for One Partner
partner_payouts:readApiAccessPermission::PARTNER_PAYOUTS_READQuery Parameters
partnerIdstringRequiredsizeintegerpageintegerResponses
Paginated payout list for the specified partner.
{
"entities": "PartnerPayout",
"count": 2,
"elements": []
}Get Payout by Partner and ID
partner_payouts:readApiAccessPermission::PARTNER_PAYOUTS_READQuery Parameters
partnerIdstringRequiredpayoutIdstringRequiredResponses
Payout details retrieved.
{
"id": "pay_5521",
"partner_id": "675d...",
"status": "pending",
"total": 1250
}Get Payout by ID
partner_payouts:readApiAccessPermission::PARTNER_PAYOUTS_READQuery Parameters
payoutIdstringRequiredResponses
Payout details retrieved.
{
"id": "pay_5521",
"partner_id": "675d...",
"status": "pending",
"total": 1250
}Update Payout Status
partner_payouts:writeApiAccessPermission::PARTNER_PAYOUTS_WRITEQuery Parameters
payoutIdstringRequiredRequest Body
{
"payout": {
"status": "paid",
"metadata": {
"reference": "BANK-TRX-2026-8891"
}
}
}payout.statusstringRequiredpayout.metadataobjectResponses
Payout status updated and related fee entries synchronized.
{
"payout": {
"id": "pay_5521",
"status": "paid"
}
}Invalid status transition.
{
"error": "Paid payouts cannot be updated"
}Stream Payout PDF
partner_payouts:readApiAccessPermission::PARTNER_PAYOUTS_READQuery Parameters
partnerIdstringRequiredpayoutIdstringRequiredResponses
Inline PDF stream response.
{
"note": "Response is streamed as application/pdf."
}