Partners

A partner is someone who earns commissions in your org. You can invite partners one at a time, or provision them from your own user base, for example when every customer can refer others.

Create a partner

curl -X POST https://referalli.com/v1/partners \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"email": "dana@example.com", "displayName": "Dana", "externalRef": "usr_8812"}'

{
  "id": "ptr_01JB...",
  "email": "dana@example.com",
  "displayName": "Dana",
  "externalRef": "usr_8812",
  "status": "active",
  "tags": [],
  "notes": "",
  "createdAt": "2026-10-21T12:00:00.000Z"
}

Unknown fields are rejected with 400 and a message naming them, such as unknown field(s): externalRefx, so a typo can't be silently ignored. A second partner with the same email or externalRef returns 409.

Provision idempotently with upsert

With "upsert": true, the call returns the partner that already has this email or externalRef (status 200) and creates one only if neither matches. That makes provisioning thousands of users one safe, repeatable call each.

• If the existing partner has no externalRef yet, the one you send is saved on it.

• If email and externalRef belong to two different partners, or the partner found by email already has a different externalRef, the call returns 409.

• Other fields (displayName, tags, notes) are only used when creating; use PATCH to change an existing partner.

Find partners

GET /v1/partners lists partners. Filters:

GET /v1/partners/{id} returns one partner. Partners in the GraphQL API also carry externalRef.

Update a partner

PATCH /v1/partners/{id} changes displayName, status, tags, notes or externalRef (send null to clear it). Unknown fields return 400.

See Commission rules for exactly what each status does to money.

Delete a partner

DELETE /v1/partners/{id} removes a partner that never did anything, together with their enrollments, links, coupons and payout profile. It needs the owner or admin role.

A partner with any history (clicks, referrals, commission lines, payouts, deals, fraud cases, contracts, or recruits of their own) can't be deleted, because the ledger and audit trail must stay intact. The call then returns 409 with partner has activity; archive it instead (status "archived").

Referral graph

In programs where customers are partners too, a referred customer can go on to refer others. GET /v1/programs/{id}/graph?root={partnerId}&depth=5 returns that tree.

A referred customer continues the tree when their customerRef equals another partner's externalRef. depth is 1 to 5 partner levels (default 5); with depth=1 you get the root and the customers it referred.

{
  "partnerId": "ptr_root",
  "displayName": "Root",
  "email": "root@example.com",
  "externalRef": "usr_root",
  "status": "active",
  "commission": [{ "currency": "usd", "amountMinor": 1000 }],
  "referrals": [
    {
      "referralId": "ref_...",
      "customerRef": "usr_mid",
      "status": "active",
      "matchedVia": "coupon",
      "ts": "2026-10-21T12:00:00.000Z",
      "revenue": [{ "currency": "usd", "amountMinor": 10000 }],
      "commission": [{ "currency": "usd", "amountMinor": 1000 }],
      "partner": {
        "partnerId": "ptr_mid",
        "commission": [{ "currency": "usd", "amountMinor": 400 }],
        "referrals": [{ "customerRef": "cus_leaf", "partner": null, "...": "..." }]
      }
    }
  ],
  "depth": 5,
  "truncated": false
}

• A partner node's commission is the net commission that partner earned in this program (earned lines plus reversals and adjustments), per currency, in minor units.

• A referral's revenue is the gross of that customer's payments; its commission is what the referring partner earned from that customer.

• Voided referrals are left out. Each partner appears at most once, so a cycle can't repeat.

• The walk stops after 5,000 referrals and sets truncated: true.

• An unknown program or root partner returns 404; a depth outside 1 to 5 returns 400.