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.

Partner records and all related financial resources are isolated to the company associated with the API token. Use partners:read|write for partner profiles and partner_payouts:read|write for payouts. Monetary snapshots created by the current payout flow use integer minor units together with an ISO 4217 currency code; decimal fields remain available for backward compatibility.

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.

{
  "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.

{
  "partner": {
    "name": "Apex Marketing Group",
    "email": "channel@apex-marketing.com",
    "external_id": "APEX_001",
    "code": "APEXPROMO",
    "partner_group_id": "66bf22b0...",
    "address": {
      "name": "Apex Marketing Group Ltd",
      "tax_number": "GB123456789",
      "country": "GB",
      "city": "London",
      "address": "1 Example Street",
      "email": "billing@apex-marketing.com",
      "legal_email": "legal@apex-marketing.com"
    }
  }
}

{
  "partner": {
    "id": "6768..."
  }
}

Creating a partner through this endpoint does not grant Partner Portal access and does not add anyone to the company backoffice. Portal access remains a separate, user-bound onboarding flow.

portal_access_mode is returned by partner read/update responses with one of disabled, active, or read_only. It is read-only in this Public API: company administrators change it from the Partner Portal settings in the backoffice, so profile integrations cannot implicitly grant or broaden portal access.

Retrieve Partner Profile

Fetch the comprehensive profile of a specific partner, including their fee structure, whitelist configuration, and association metadata.

{
  "id": "66b136b9...",
  "name": "Apex Marketing Group",
  "status": "active",
  "tags": [
    "tier-1",
    "mfa-enabled"
  ],
  "email": "channel@apex-marketing.com",
  "legal_address": {
    "city": "London",
    "country": "GB",
    "tax_number": "GB123..."
  },
  "portal_access_mode": "active"
}

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.

{
  "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.

{
  "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.

{
  "entities": "PartnerFees",
  "elements": [
    {
      "id": "fee_991",
      "fee_value": 15.5,
      "calculated_fee_minor": 1550,
      "currency": "EUR",
      "currency_config_version": 3,
      "status": "pending"
    }
  ]
}

Create an Offline Payout

Consolidate available commission fees into the operational payout record used by the backoffice and Partner Portal. The partner supplies the actual invoice details, while invoice delivery and payment take place offline. This endpoint does not generate a self-billing or fiscal document.

{
  "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"
    }
  }
}

{
  "id": "pay_5521",
  "total": 1250,
  "subtotal_minor": 102459,
  "tax_minor": 22541,
  "total_minor": 125000,
  "currency": "EUR",
  "status": "pending"
}

{
  "error": "The idempotency key was used with a different payload."
}

{
  "error": "A selected fee is already assigned to a payout."
}

{
  "error": "The selected fees do not reach the minimum payout amount."
}

{
  "error": "The company currency must be persisted before financial operations are enabled."
}

The server derives the currency and its configuration version from the company configuration. Mixed-currency requests are rejected. Replaying the same request with the same idempotency key returns the existing payout and never claims the same fee twice. After a payout is refused, use a new idempotency key when intentionally creating a new payout from the released fees.

Retrieve Payout Documentation (PDF)

Retrieve a base64-encoded operational payout report. It is an account statement for the payout and is not the partner invoice or a platform-generated fiscal document.

{
  "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 response = await fetch("https://api.example.com/2026-02-01/partners/payouts.json", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json",
      "Idempotency-Key": "payout-PARTNER_6621-2026-03-03-001"
    },
    body: JSON.stringify(payoutData)
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const settlement = await response.json();
  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

{
  "id": "675d...",
  "name": "Apex Marketing Group",
  "email": "channel@apex-marketing.com"
}

{
  "error": "A valid \"externalId\" or \"email\" must be specified in the request"
}

Update Partner Profile

{
  "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": {
      "name": "Apex Marketing Group Ltd",
      "tax_number": "GB123456789",
      "country": "GB",
      "city": "London",
      "state": "",
      "postal_code": "SW1A 1AA",
      "address": "1 Example Street",
      "email": "billing@apex-marketing.com",
      "legal_email": "legal@apex-marketing.com"
    }
  }
}

{
  "id": "675d...",
  "name": "Apex Marketing Group - Enterprise",
  "portal_access_mode": "active"
}

state and postal_code are optional. A billing profile needs at least one of vat_number or tax_number before the company can approve it. Updating Address data changes its canonical review hash, so any previous billing approval no longer applies to the modified data. The API never updates encrypted payment coordinates.

portal_access_mode in the response reflects the company-controlled Portal policy. Supplying it in this update payload has no effect; use the dedicated backoffice controls for disabled, active, and read_only transitions.

Delete Partner

{
  "id": "675d...",
  "deleted": true
}

{
  "error": "Unable to remove this partner. Customer attached to partner: ..."
}

Get Partner Fee by ID

{
  "id": "fee_991",
  "partner_id": "675d...",
  "fee_value": 15.5,
  "status": "pending"
}

List Global Payouts

{
  "entities": "PartnerPayout",
  "count": 3,
  "elements": [
    {
      "id": "pay_5521",
      "total": 1250,
      "total_minor": 125000,
      "currency": "EUR",
      "status": "pending",
      "partner_id": "675d..."
    }
  ]
}

List Payouts for One Partner

{
  "entities": "PartnerPayout",
  "count": 2,
  "elements": [
    {
      "id": "pay_5521",
      "total": 1250,
      "total_minor": 125000,
      "currency": "EUR",
      "status": "pending",
      "partner_id": "675d..."
    }
  ]
}

Get Payout by Partner and ID

{
  "id": "pay_5521",
  "partner_id": "675d...",
  "status": "pending",
  "total": 1250,
  "total_minor": 125000,
  "currency": "EUR",
  "currency_config_version": 3
}

Get Payout by ID

{
  "id": "pay_5521",
  "partner_id": "675d...",
  "status": "pending",
  "total": 1250,
  "total_minor": 125000,
  "currency": "EUR",
  "currency_config_version": 3
}

Update Payout Status

{
  "payout": {
    "status": "paid",
    "metadata": {
      "reference": "BANK-TRX-2026-8891"
    }
  }
}

{
  "payout": {
    "id": "pay_5521",
    "status": "paid"
  }
}

{
  "error": "Paid payouts cannot be updated"
}

Setting a payout to refused releases all associated fees idempotently, making them available for a later payout. Setting it to paid marks the fees as paid and is terminal: a paid payout cannot return to pending or refused.

Stream Payout PDF

{
  "note": "Response is streamed as application/pdf."
}