Referrals
Referrals endpoints of the Zanfia Workspace API, with schemas and code samples.
Referral programs (Marketing → Referral programs) come in two modes, set by kind when you create the program. kind: referral ("Referral rewards") rewards participants, your customers, for referred purchases through a milestone ladder (milestones). kind: affiliate ("Affiliate program") pays partners a commission on each referred buyer's first purchase (commission: percent or flat, holdDays); the API creates, updates and archives these programs and enrolls partners by client id, while commissions and their settlement (approve, reject, mark paid) are handled in the panel. Creating or activating a program and enrolling anyone needs the Growth plan or higher (403 feature_not_available below it). Programs start inactive; activate them via PATCH. Participants are your workspace clients: enroll one by client id, or (Referral rewards only) every client of the program's products at once; enroll-all on an affiliate program answers 400 not-referral-program. Each participant 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. All routes require a Authorization: Bearer header — see Authentication.
List referral programs
/referral-programsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Response Body
application/json
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 }, "countFormSignups": true, "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
/referral-programsAuthorization
bearerAuth 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).
Response Body
application/json
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 }, "countFormSignups": true, "stats": { "participants": 0, "validReferrals": 0, "invalidReferrals": 0, "rewardsEarned": 0, "rewardsPendingApproval": 0, "rewardsDelivered": 0 }, "createdAt": "string", "updatedAt": "string" }}{ "error": "string", "message": "string"}Program detail (dashboard)
/referral-programs/{programId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Response Body
application/json
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 }, "countFormSignups": true, "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
/referral-programs/{programId}Authorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
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 }, "countFormSignups": true, "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
/referral-programs/{programId}/archiveAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Response Body
application/json
application/json
curl -X POST "https://example.com/referral-programs/string/archive"{ "archived": true}{ "error": "string", "message": "string"}Enroll a client
/referral-programs/{programId}/participantsAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
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
/referral-programs/{programId}/participants/enroll-allAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Response Body
application/json
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
/referral-programs/{programId}/rewards/{entryId}/resolveAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
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
/referral-programs/{programId}/rewards/{entryId}/retry-deliveryAuthorization
bearerAuth API key from Dashboard → Integrations → API, MCP and CLI.
In: header
Path Parameters
Response Body
application/json
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?