update_referral_program
Set up or change a project's Referral Program. The first call creates it; later calls change only the arguments present. Emits referral.program_updated.
Write the programme's settings without restating them. A project holds one programme, so there is
no create tool: the first call on a project creates it and every later call changes only the
arguments present, the way the REST PUT behaves. The arguments are typed here (an enum word, a
whole number, a list of the project's plan ids); whether the shape adds up is the service's rule,
the same one the dashboard relies on, answered as VALIDATION_FAILED.
Synchronous — the programme after the change comes back, and
referral.program_updated emits once with the
fields that moved.
Omit to keep, send null to clear
Leaving an argument out leaves it alone. commission_period_months: null
makes a percentage commission run for life; minimum_payout,
payout_details_label, terms and commission_currency_id accept null
for none.
A change tells every affiliate
Rewards already in the ledger keep their figures: a change is never retroactive. Every approved or pending affiliate is told the new terms in their chat and by mail when a field they were promised moves: the reward, the commission, the hold, the friend's reward or the creator's own terms. Who may join, the payout label and the minimum payout are the creator's side and send nothing.
Requires the Referral Program Addon or a Growth plan on the project owner. When the plan lacks it
the call fails with TEAM_TIER_REQUIRED and nothing is written.
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
A client that honours annotations asks a person before running it. Sending the same arguments twice changes nothing the second time. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
project_id*stringUUID of the project whose Referral Program to set up or change.
activebooleanoptionalThe on/off switch. Prefer activate_referral_program and deactivate_referral_program, which change only this.
customers_onlybooleanoptionalWhether only members with a live membership may join.
approval_requiredbooleanoptionalWhether the creator approves each affiliate before their code counts.
reward_kindstringoptional"free_days" (membership days banked on the referrer) or "cash" (a commission the creator pays out themselves).
reward_daysintegeroptionalDays a referrer earns per converted friend, 1..3650; for a free_days reward.
1max3650commission_typestringoptional"percentage" of every settled payment or a "fixed" amount on the first; for a cash reward.
commission_valuenumberoptionalThe rate: 0.0001..100 for a percentage, any amount above zero for a fixed commission.
commission_currency_idstringoptionalCurrency UUID a fixed commission is paid in; ignored and cleared for a percentage.
commission_period_monthsintegeroptionalHow long a percentage commission runs after conversion: 0 for the friend's first payment only, 1..36 months, or null for life.
0max36hold_daysintegeroptionalDays a cash commission waits before it is payable, 0..90.
0max90minimum_payoutnumberoptionalA guide for the creator, the balance an affiliate reaches before they pay; nothing is enforced. Pass null for none.
friend_reward_kindstringoptionalWhat a referred friend receives on their first purchase: "none", "free_days" or "coupon".
friend_reward_daysintegeroptionalDays banked on the friend's first purchase, 1..3650; for a free_days friend reward.
1max3650friend_coupon_idstringoptionalUUID of one of the project's coupon codes, applied at the friend's checkout; for a coupon friend reward.
payout_details_labelstringoptionalThe question affiliates answer so the creator can pay them, such as "PayPal email"; at most 120 characters, null for none.
termsstringoptionalThe creator's own terms, shown to affiliates and referred friends; at most 5,000 characters, null for none.
plan_idsstring[]optionalPlan UUIDs a conversion must be on to count. An empty list counts every plan in the project, including ones added later.
What it returns
{ "data": { "id": "6e2a7a4f-3b8c-4c21-9f6d-2a3b4c5d6e7f", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "active": true, "customers_only": false, "approval_required": false, "reward_kind": "cash", "reward_days": null, "commission_type": "percentage", "commission_value": "20.0000", "commission_currency_id": null, "commission_currency": null, "commission_period_months": 6, "hold_days": 14, "minimum_payout": "50.0000", "friend_reward_kind": "free_days", "friend_reward_days": 3, "friend_coupon_id": null, "payout_details_label": "PayPal email", "terms": "One referral per household.", "plan_ids": [], "created_at": "2026-10-01T09:14:02+00:00", "updated_at": "2026-10-08T16:41:11+00:00" }}The whole programme comes back, not only the fields sent, so there is no need for a follow-up
get_referral_program.
How it fails
TEAM_TIER_REQUIREDthe project owner's plan does not include the Referral Program.
VALIDATION_FAILEDone entry per offending field in error.context: an enum word outside its
RESOURCE_NOT_FOUNDunknown project_id, a project on another team, or one outside the token's
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-referral:update.
Related
How is this guide?
Last updated on