suspend_referral_affiliate
Stop an affiliate earning — their code no longer counts new friends, while what they earned stays. Destructive. Emits referral.affiliate_suspended.
Take an affiliate out of the programme without touching what they earned. Their code stops counting
new friends and nothing new is earned; commissions already in the ledger stay and can still be paid
out. It emits referral.affiliate_suspended.
Destructive — a real person stops earning
Confirm the target with the creator before calling. The affiliate is not told by the tool; the creator decides what to say.
Idempotent: an affiliate already suspended is left as they are and nothing is emitted.
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.
Arguments
project_id*stringUUID of the project the affiliate belongs to.
affiliate_id*stringUUID of the affiliate to suspend.
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": "suspended", "days_balance": 0, "balances": [], "joined_at": "2026-10-08T09:05:00+00:00", "approved_at": "2026-10-08T10:00:00+00:00", "created_at": "2026-10-08T09:05:00+00:00", "updated_at": "2026-10-09T08:30:00+00:00" }}The get_referral_affiliate row after the change.
How it fails
VALIDATION_FAILEDthe caller is a team member whose role lacks the team's referral-update
RESOURCE_NOT_FOUNDunknown project_id or affiliate_id, an affiliate of another project, or a
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-referral:update.
How is this guide?
Last updated on
record_referral_payout
Record money the creator paid an affiliate outside Subscriby, so the ledger marks their oldest payable commissions as paid. Destructive. Emits referral.payout_recorded.
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.