Referrals

Referrals endpoints of the Zanfia Workspace API, with schemas and code samples.

5 min readLast updated Sep 10, 2026

Referral programs (Marketing → Referrals): a program targets one or more of your products and rewards participants for referred purchases through a milestone ladder (kind: referral; affiliate commission terms are modeled but not yet executable). Programs start inactive — activate them via PATCH. Participants are your workspace clients: enroll one by client id or every client of the program's products at once; each gets a referral code that travels as ?ref= through checkout. Rewards with approval: manual wait in pendingRewards for your verdict; failed deliveries land in failedDeliveries for a retry. All routes require a Authorization: Bearer header — see Authentication.

List referral programs

GET/referral-programs

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/referral-programs"

{  "programs": [    {      "id": "string",      "kind": "referral",      "name": "string",      "status": "active",      "productIds": [        "string"      ],      "attribution": {        "windowDays": 0,        "allowCouponAttribution": true,        "twoSidedDiscountId": "string"      },      "enrollment": "open",      "milestones": [        {          "id": "string",          "threshold": 0,          "recurring": true,          "approval": "automatic",          "reward": {            "type": "productAccess",            "productId": "string",            "priceId": "string",            "accessDays": 0          },          "emailTemplate": {            "subject": "string",            "html": "string"          }        }      ],      "commission": {        "type": "percent",        "value": 0,        "appliesTo": "firstOrder",        "holdDays": 0      },      "stats": {        "participants": 0,        "validReferrals": 0,        "invalidReferrals": 0,        "rewardsEarned": 0,        "rewardsPendingApproval": 0,        "rewardsDelivered": 0      },      "createdAt": "string",      "updatedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Create a referral program

POST/referral-programs

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Referrals 2.0 creator-side HTTP contract (products-service products.v1).

kind*ReferralProgramKind

Referrals 2.0 — workspace-native referral/affiliate programs.

Replaces the legacy per-product ProductReferralsDocument (engine in the deprecated apps/functions). Both shapes coexist in the same referral-programs collection during migration: legacy docs are keyed by productId and have no kind field; v2 docs are keyed by their own rprog_* id and always carry kind. Readers distinguish by kind.

Plan: plans/zanfia-2.0/referrals/rebuild-plan.md

Value in

"referral"
"affiliate"

name*string

productIds*array<string>

milestones?array<>

commission?|null

attribution?

enrollment?ReferralEnrollmentMode

How participants join an affiliate-kind program. Referral-kind programs are always effectively open to existing clients.

Value in

"open"
"inviteOnly"
"closed"

status?string

Value in

"active"
"inactive"

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs" \  -H "Content-Type: application/json" \  -d '{    "kind": "referral",    "name": "string",    "productIds": [      "string"    ]  }'

{  "program": {    "id": "string",    "kind": "referral",    "name": "string",    "status": "active",    "productIds": [      "string"    ],    "attribution": {      "windowDays": 0,      "allowCouponAttribution": true,      "twoSidedDiscountId": "string"    },    "enrollment": "open",    "milestones": [      {        "id": "string",        "threshold": 0,        "recurring": true,        "approval": "automatic",        "reward": {          "type": "productAccess",          "productId": "string",          "priceId": "string",          "accessDays": 0        },        "emailTemplate": {          "subject": "string",          "html": "string"        }      }    ],    "commission": {      "type": "percent",      "value": 0,      "appliesTo": "firstOrder",      "holdDays": 0    },    "stats": {      "participants": 0,      "validReferrals": 0,      "invalidReferrals": 0,      "rewardsEarned": 0,      "rewardsPendingApproval": 0,      "rewardsDelivered": 0    },    "createdAt": "string",    "updatedAt": "string"  }}

{  "error": "string",  "message": "string"}

Program detail (dashboard)

GET/referral-programs/{programId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Response Body

`application/json`

curl -X GET "https://example.com/referral-programs/string"

{  "program": {    "id": "string",    "kind": "referral",    "name": "string",    "status": "active",    "productIds": [      "string"    ],    "attribution": {      "windowDays": 0,      "allowCouponAttribution": true,      "twoSidedDiscountId": "string"    },    "enrollment": "open",    "milestones": [      {        "id": "string",        "threshold": 0,        "recurring": true,        "approval": "automatic",        "reward": {          "type": "productAccess",          "productId": "string",          "priceId": "string",          "accessDays": 0        },        "emailTemplate": {          "subject": "string",          "html": "string"        }      }    ],    "commission": {      "type": "percent",      "value": 0,      "appliesTo": "firstOrder",      "holdDays": 0    },    "stats": {      "participants": 0,      "validReferrals": 0,      "invalidReferrals": 0,      "rewardsEarned": 0,      "rewardsPendingApproval": 0,      "rewardsDelivered": 0    },    "createdAt": "string",    "updatedAt": "string"  },  "participants": [    {      "id": "string",      "clientId": "string",      "refCode": "string",      "email": "string",      "firstName": "string",      "lastName": "string",      "status": "active",      "enrolledVia": "self",      "stats": {        "validReferrals": 0,        "invalidReferrals": 0,        "pendingReferrals": 0,        "rewardsEarned": 0,        "rewardsDelivered": 0,        "accruedCommission": 0,        "reversedCommission": 0      },      "createdAt": "string",      "updatedAt": "string"    }  ],  "pendingRewards": [    {      "id": "string",      "participantId": "string",      "refCode": "string",      "type": "referral",      "milestoneId": "string",      "milestoneOccurrence": 0,      "rewardType": "productAccess",      "approval": "automatic",      "rewardStatus": "pendingApproval",      "deliveredAt": "string",      "createdAt": "string",      "updatedAt": "string"    }  ],  "failedDeliveries": [    {      "id": "string",      "participantId": "string",      "refCode": "string",      "type": "referral",      "milestoneId": "string",      "milestoneOccurrence": 0,      "rewardType": "productAccess",      "approval": "automatic",      "rewardStatus": "pendingApproval",      "deliveredAt": "string",      "createdAt": "string",      "updatedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Update a referral program

PATCH/referral-programs/{programId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

status?string

Value in

"active"
"inactive"

productIds?array<string>

milestones?array<>

commission?|null

attribution?

enrollment?ReferralEnrollmentMode

How participants join an affiliate-kind program. Referral-kind programs are always effectively open to existing clients.

Value in

"open"
"inviteOnly"
"closed"

Response Body

`application/json`

curl -X PATCH "https://example.com/referral-programs/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "program": {    "id": "string",    "kind": "referral",    "name": "string",    "status": "active",    "productIds": [      "string"    ],    "attribution": {      "windowDays": 0,      "allowCouponAttribution": true,      "twoSidedDiscountId": "string"    },    "enrollment": "open",    "milestones": [      {        "id": "string",        "threshold": 0,        "recurring": true,        "approval": "automatic",        "reward": {          "type": "productAccess",          "productId": "string",          "priceId": "string",          "accessDays": 0        },        "emailTemplate": {          "subject": "string",          "html": "string"        }      }    ],    "commission": {      "type": "percent",      "value": 0,      "appliesTo": "firstOrder",      "holdDays": 0    },    "stats": {      "participants": 0,      "validReferrals": 0,      "invalidReferrals": 0,      "rewardsEarned": 0,      "rewardsPendingApproval": 0,      "rewardsDelivered": 0    },    "createdAt": "string",    "updatedAt": "string"  }}

{  "error": "string",  "message": "string"}

Archive a referral program

POST/referral-programs/{programId}/archive

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/archive"

{  "archived": true}

{  "error": "string",  "message": "string"}

Enroll a client

POST/referral-programs/{programId}/participants

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

clientId*string

email*string

firstName?string|null

lastName?string|null

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/participants" \  -H "Content-Type: application/json" \  -d '{    "clientId": "string",    "email": "string"  }'

{  "participant": {    "id": "string",    "clientId": "string",    "refCode": "string",    "email": "string",    "firstName": "string",    "lastName": "string",    "status": "active",    "enrolledVia": "self",    "stats": {      "validReferrals": 0,      "invalidReferrals": 0,      "pendingReferrals": 0,      "rewardsEarned": 0,      "rewardsDelivered": 0,      "accruedCommission": 0,      "reversedCommission": 0    },    "createdAt": "string",    "updatedAt": "string"  },  "alreadyEnrolled": true}

{  "error": "string",  "message": "string"}

Enroll every client of the program products

POST/referral-programs/{programId}/participants/enroll-all

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/participants/enroll-all"

{  "enrolled": 0,  "alreadyEnrolled": 0,  "skippedWithoutAccount": 0}

{  "error": "string",  "message": "string"}

Approve or reject a pending reward

POST/referral-programs/{programId}/rewards/{entryId}/resolve

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

entryId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

decision*string

Value in

"approve"
"reject"

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/rewards/string/resolve" \  -H "Content-Type: application/json" \  -d '{    "decision": "approve"  }'

{  "decision": "approve",  "delivered": true}

{  "error": "string",  "message": "string"}

Retry a failed reward delivery

POST/referral-programs/{programId}/rewards/{entryId}/retry-delivery

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

entryId*string

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/rewards/string/retry-delivery"

{  "delivered": true}

{  "error": "string",  "message": "string"}

Was this article helpful?

Spotted something off? Tell us at support@zanfia.com.

List referral programs

200application/json

4XXapplication/json

Create a referral program

200application/json

4XXapplication/json

Program detail (dashboard)

200application/json

4XXapplication/json

Update a referral program

200application/json

4XXapplication/json

Archive a referral program

200application/json

4XXapplication/json

Enroll a client

200application/json

4XXapplication/json

Enroll every client of the program products

200application/json

4XXapplication/json

Approve or reject a pending reward

200application/json

4XXapplication/json

Retry a failed reward delivery

200application/json

4XXapplication/json

Related articles

API overview

Authentication and API keys

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`