Set up or change the programme

curl -X PUT https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/referral-program \  -H "Authorization: Bearer sbt_..." \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{    "reward_kind": "cash",    "commission_type": "percentage",    "commission_value": 20,    "commission_period_months": 6,    "hold_days": 14,    "friend_reward_kind": "free_days",    "friend_reward_days": 3,    "payout_details_label": "PayPal email",    "terms": "One referral per household."  }'

The first PUT creates the programme and answers 201; every later PUT changes only the fields it carries and answers 200. Omitting a field keeps its stored value; a first save without reward_kind is a free-days programme, and without friend_reward_kind gives friends nothing.

Changing the terms is not retroactive, and the affiliates are told. Rewards already in the ledger keep their figures. Every approved or pending affiliate receives 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 your own terms text. Who may join, the payout label and the minimum payout are your side and send nothing.

Requires ability

project-referral:update

The token must hold this ability, or the call is refused with 403.

Fires one event

referral.program_updated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

update_referral_program

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesOptionalapplication/json

The Referral Program settings: what referrers earn, what their friends receive, who may join and which plans count. The first PUT creates the programme; every later PUT changes only the fields it carries.

active?boolean

The on/off switch. Prefer the activate and deactivate endpoints, which fire the same event with only that change.

customers_only?boolean

Whether only members with a live membership may join. Defaults to false.

approval_required?boolean

Whether you approve each affiliate before their code counts. Defaults to false.

reward_kind?ReferralRewardKind

free_days (membership days banked on the referrer) or cash (a commission you pay out yourself). Defaults to free_days on a first save.

Value in

"free_days"
"cash"

reward_days?|

Days a referrer earns per converted friend, 1 to 3650; required when reward_kind is free_days.

Range1 <= value <= 3650

commission_type?|

percentage of every settled payment or a fixed amount on the first; required when reward_kind is cash.

commission_value?|

The rate: 0.0001 to 100 for a percentage, any amount above zero for a fixed commission. Stored as a decimal string with four places.

commission_currency_id?|

The currency a fixed commission is paid in; required then, cleared for a percentage.

commission_period_months?|

How long a percentage commission runs after conversion: 0 for the friend's first payment only, 1 to 36 months, or null for life. A fixed commission is always the first payment only.

Range0 <= value <= 36

hold_days?integer

Days a cash commission waits before it is payable, so a refund inside the window can take it back: 0 to 90. Defaults to 14.

Range0 <= value <= 90

minimum_payout?|

A guide for you, the balance an affiliate reaches before you pay; nothing is enforced. Null for none.

friend_reward_kind?ReferralFriendRewardKind

What a referred friend receives on their first purchase: none, free_days or coupon. Defaults to none.

Value in

"none"
"free_days"
"coupon"

friend_reward_days?|

Days banked on the friend's first purchase, 1 to 3650; required when friend_reward_kind is free_days.

Range1 <= value <= 3650

friend_coupon_id?|

One of this project's coupon codes, applied at the friend's checkout; required when friend_reward_kind is coupon. Needs coupon codes on the project owner's plan.

payout_details_label?|

The question affiliates answer so you can pay them, such as PayPal email; at most 120 characters. Null for none.

Lengthlength <= 120

terms?|

Your own terms, shown to affiliates and referred friends; at most 5,000 characters. Null for none.

Lengthlength <= 5000

plan_ids?array<>

Restrict conversions to these plans of the project, at most 200. Omit to leave the restriction alone; send [] for every plan, including plans added later.

Itemsitems <= 200

Responses

200OKapplication/json

The programme as written: 201 when this call created it, 200 after.

response-200?string

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*