Referral Program

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.

put/v1/projects/{project}/referral-program

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/projects/{project}/referral-program
  • Auth: HTTP bearer

Path parameters

projectstring uuid required

The project, resolved by the route binder.

Headers

Idempotency-Keystring uuid required

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.

Request body

activeboolean

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

customers_onlyboolean

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

approval_requiredboolean

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

reward_kind'free_days' | 'cash'

What a referrer earns per referral: membership time, or money the creator pays out. Two kinds and no third, because every other shape a creator asked for (a coupon for the referrer, store credit) is one of these in disguise and each adds a surface the Payouts tab would have to explain.

reward_daysinteger nullable

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

commission_type'percentage' | 'fixed'

How a cash commission is worked out from a settled payment. A percentage rides every payment in the commission period, in the currency the payment settled in. A fixed amount is paid once, on the first payment, in the currency the programme names: a fixed sum per renewal would make a weekly plan pay a referrer more than the plan earns.

commission_valuenumber nullable

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_idstring nullable

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

commission_period_monthsinteger nullable

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.

hold_daysinteger

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.

minimum_payoutnumber nullable

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

friend_reward_kind'none' | 'free_days' | 'coupon'

What the referred friend receives for arriving through a referral, if anything. Days are banked on the friend's first purchase the moment it settles; a coupon is applied at their checkout and follows the coupon's own rules, which is why it is offered only to creators who hold the Coupons capability.

friend_reward_daysinteger nullable

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

friend_coupon_idstring nullable

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_labelstring nullable

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

termsstring nullable

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

plan_idsstring[]

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.

Response

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

string required

Changes

No recorded changes to this operation across all 1 revision of this API.