Commissions

A Commission is a row in the immutable ledger that says “partner X earned amount Y on event Z.” Status transitions: accrued → approved → paid, or accrued → reversed (refund / chargeback / fraud).

GET /commissions

List commissions across all partners on the tenant.

Auth: Admin API key OR scoped key with commissions:read.

GET <base>/commissions?status=accrued&limit=100
Authorization: Bearer <key>

Query	Notes
status	One of accrued, approved, paid, reversed. Omitted = all.
limit	1–500, default 100.

Response

{
  "commissions": [
    {
      "id": "01HXX...",
      "tenantId": "01HXX...",
      "attributionId": "01HXX...",
      "partnerId": "01HXX...",
      "amount": "12.00",
      "currency": "USD",
      "status": "accrued",
      "accruedAt": "2026-04-24T12:00:00Z",
      "approvedAt": null,
      "paidAt": null,
      "holdbackDays": 30,
      "campaignId": "cmp_default",
      "campaignName": "Default 20% revshare",
      "matureAt": "2026-05-24T12:00:00Z"
    }
  ]
}

matureAt is accruedAt + holdbackDays — when the commission is eligible for auto-approval. null if the campaign has no holdback configured.

holdbackDays is the effective holdback: the partner’s snapshotted PartnerCommission.holdbackDays if set, otherwise the campaign’s holdbackDays (see snapshot model).

GET /partners/:id/commissions

Same shape, scoped to a single partner.

Auth: Admin API key OR the partner themselves (via partner-scoped key) OR scoped key with commissions:read.

Commission snapshot model

When a creator’s PartnershipRequest is approved (Network flow) OR a partner is created directly (admin invite with commissionSnapshot), the offering’s commission terms are stamped onto a PartnerCommission row alongside the Partner. Future commissions for that partner compute from the snapshot, not from the live Campaign rule.

This means:

• A brand can edit a Campaign’s commission rate or holdback after partners have signed up — existing partners keep the rate they were approved under, only new partners get the new rate.

• Each partner’s Commission row computes via:

  rate = PartnerCommission.commissionValue if PartnerCommission exists for this partner,
         else Campaign.commissionRule.value
  holdback = coalesce(PartnerCommission.holdbackDays, Campaign.holdbackDays)

• GET /partners/:id/commission-snapshot returns the row (see partners).

• Admin overrides via the Commission link on each partner row in Admin → Partners — writes a PartnerCommission with source = 'amendment'.

Past commissions are never recomputed when the snapshot or campaign rule changes — only events accruing after the change use the new value.