add_referral_affiliate
Enrol a member of a project as an affiliate by hand, approved whatever the programme's switches say. Emits referral.affiliate_joined.
The creator enrolling a member themselves. The member is resolved within the project, so a foreign
id is RESOURCE_NOT_FOUND, and the shared Action approves them on the spot whatever the
customers-only and approval switches say, hands them their code, their links and the programme's
terms in their chat and by mail, and emits
referral.affiliate_joined.
A member joins once
A member who already stands in the programme, pending, approved or
suspended, is refused with VALIDATION_FAILED; use
approve_referral_affiliate to bring a
pending or suspended one back.
Requires the Referral Program Addon or a Growth plan on the project owner, and a live programme.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
project_id*stringUUID of the project whose Referral Program the member joins.
member_id*stringUUID of the member to enrol, as list_subscribers lists them.
What it returns
{ "data": { "id": "0b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "program_id": "6e2a7a4f-3b8c-4c21-9f6d-2a3b4c5d6e7f", "member_id": "a1b2c3d4-e5f6-4718-8a9b-0c1d2e3f4a5b", "code": "ADA2026", "status": "approved", "days_balance": 0, "balances": [], "joined_at": "2026-10-08T09:05:00+00:00", "approved_at": "2026-10-08T09:05:00+00:00", "created_at": "2026-10-08T09:05:00+00:00", "updated_at": "2026-10-08T09:05:00+00:00" }}The get_referral_affiliate row, balances empty
because nothing is earned yet.
How it fails
TEAM_TIER_REQUIREDthe project owner's plan does not include the Referral Program.
VALIDATION_FAILEDthe member already stands in the programme, or the caller's role lacks the
RESOURCE_NOT_FOUNDunknown project_id, a project with no programme, or a member_id that is not
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-referral:create.
How is this guide?
Last updated on
activate_referral_program
Switch a project's Referral Program on so links attribute and payments earn again. Emits referral.program_updated.
approve_referral_affiliate
Approve a pending or suspended affiliate so their code counts from now on; they receive their link and the terms. Emits referral.affiliate_approved.