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.
File a payout that already happened. Subscriby never moves the money: the creator pays the
affiliate by whatever means they agreed, then records it here, and the ledger marks the affiliate's
oldest payable commissions in that currency as paid, first in first out, until the amount is
covered. It emits referral.payout_recorded.
Destructive — it records that money left
Read the affiliate's balances with
get_referral_affiliate first and confirm the
amount with the creator. payable in the currency is the most a payout may
record; pending commissions are still inside the hold and cannot be paid
yet.
The amount is typed here; whether it exceeds the balance is the Action's rule, answered as
VALIDATION_FAILED with the payable balance in error.context.balance.
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.
Arguments
project_id*stringUUID of the project the affiliate belongs to.
affiliate_id*stringUUID of the affiliate who was paid.
amount*numberWhat was paid, greater than zero and at most the affiliate's payable balance in the currency.
currency_id*stringUUID of the currency the commissions were earned in; a balance exists per currency.
referencestringoptionalThe creator's own reference, such as a transfer id; at most 120 characters.
notestringoptionalA note for the creator's records; at most 1,000 characters.
What it returns
{ "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "affiliate_id": "0b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b", "amount": "30.0000", "currency_id": "f0e1d2c3-b4a5-4697-8877-665544332211", "currency": "USD", "reference": "PAYPAL-7F3D1C92", "note": null, "paid_at": "2026-11-01T10:00:00+00:00", "recorded_by_user_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70", "rewards_paid": 3, "created_at": "2026-11-01T10:00:00+00:00" }}The same row list_referral_payouts emits.
How it fails
VALIDATION_FAILEDamount is not above zero or exceeds the payable balance in that currency
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
list_referrals
List the friends affiliates brought in — how each arrived, whether they paid, and until when the affiliate earns on them. Read-only, paginated.
suspend_referral_affiliate
Stop an affiliate earning — their code no longer counts new friends, while what they earned stays. Destructive. Emits referral.affiliate_suspended.