--- title: "Switch the programme off" method: POST path: "/v1/projects/{project}/referral-program/deactivate" tags: ["Referral Program"] --- # Switch the programme off `POST /v1/projects/{project}/referral-program/deactivate` ## Request - Base URL: `https://api.subscriby.net` - URL: `https://api.subscriby.net/v1/projects/{project}/referral-program/deactivate` - Auth: HTTP bearer ```bash curl -X POST https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/referral-program/deactivate \ -H "Authorization: Bearer sbt_..." \ -H "Idempotency-Key: $(uuidgen)" ``` The safe way to stop: links stop attributing and payments stop earning at once, while the ledger and the payouts stay readable and every affiliate is told their link no longer counts new friends. Emits `referral.program_updated`. Answers `200` with the programme. ## Path parameters - `project` string, uuid, required ## Headers - `Idempotency-Key` string, uuid, required ## Response `200` The programme after the change. - object - `data` ReferralProgramResource, required: A project's Referral Program: what referrers earn, what their friends receive on their first purchase, who may join, how long a commission is held, and which plans count. - `id` string, required: The programme's id. A project holds one programme. - `project_id` string, required: The project that runs it. - `active` boolean, required: The creator's on/off switch. A paused programme attributes nothing and earns nothing; what affiliates already earned stays. - `customers_only` boolean, required: Whether only members with a live membership may join. - `approval_required` boolean, required: Whether the creator approves each affiliate before their code counts. - `reward_kind` string, required: `free_days` (membership days banked on the referrer) or `cash` (a commission the creator pays out themselves). - `reward_days` integer, nullable, required: Days a referrer earns per converted friend on a `free_days` programme; null on a cash one. - `commission_type` string, nullable, required: `percentage` of every settled payment or a `fixed` amount on the first; null on a `free_days` programme. - `commission_value` string, nullable, required: The rate as a decimal string with four places: `"20.0000"` for 20%, `"10.0000"` for ten of the commission currency. Parse it as a decimal, never a float. - `commission_currency_id` string, nullable, required: The currency a `fixed` commission is paid in; null for a percentage, which is earned in each payment's own currency. - `commission_currency` string, nullable: That currency's ISO 4217 code, present only when the relation is loaded: on a single read and every write, not on a list row. - `commission_period_months` integer, nullable, required: How long a percentage commission runs after conversion: `0` for the friend's first payment only, a number of months, or null for life. Always `0` on a fixed commission. - `hold_days` integer, required: Days a cash commission waits before it is payable, so a refund inside the window can take it back. - `minimum_payout` string, nullable, required: A guide for the creator, the balance an affiliate reaches before they pay; nothing is enforced. Null for none. - `friend_reward_kind` string, required: What a referred friend receives on their first purchase: `none`, `free_days` or `coupon`. - `friend_reward_days` integer, nullable, required: Days banked on the friend's first purchase on a `free_days` friend reward; null otherwise. - `friend_coupon_id` string, nullable, required: The coupon applied at the friend's checkout on a `coupon` friend reward; null otherwise. - `payout_details_label` string, nullable, required: The question affiliates answer so the creator can pay them, such as `PayPal email`; null for none. - `terms` string, nullable, required: The creator's own terms, shown to affiliates and referred friends; null for none. - `plan_ids` object, required: The plans a conversion must be on to count. An empty array means **every** plan in the project, including plans added later, not no plans. - `created_at` string, nullable, required: When the programme was set up, ISO 8601. - `updated_at` string, nullable, required: When it last changed, ISO 8601. ## Other responses - `400`: `IDEMPOTENCY_KEY_MISSING`: every write needs an `Idempotency-Key` header. Send a fresh UUID per distinct operation. - `401`: `AUTHENTICATION_REQUIRED`: the request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an `sbt_test_` token on production). - `403`: `TOKEN_MISSING_ABILITY`: the token is valid but does not carry the ability this endpoint requires; `error.context.required_ability` names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers `FORBIDDEN`, `TEAM_TIER_REQUIRED` or `CONNECTOR_TIER_REQUIRED` with the same status, and says so in its own description. On this endpoint: `TEAM_TIER_REQUIRED`: when the creator has neither the Referral Program Addon nor a Growth plan. - `404`: `RESOURCE_NOT_FOUND`: an id in the path names nothing the token can see. `TENANT_MISMATCH`: the project sits outside the token's `scope:project:` allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. On this endpoint: `RESOURCE_NOT_FOUND`: while the project has no programme. - `409`: `IDEMPOTENCY_KEY_REUSED`: the key was already used in the last 24 hours with a different request body. - `425`: `IDEMPOTENCY_REPLAY_IN_PROGRESS`: the first request with this key is still running; retry in a few seconds and the original response is replayed. - `429`: `RATE_LIMITED`: the token has spent its 300 requests a minute or 10,000 an hour; `Retry-After` says when the next one is accepted. --- [API](https://skmtc.dev/memberpass/apis/subscriby-rest-api.md) · [All operations](https://skmtc.dev/memberpass/apis/subscriby-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/memberpass/apis/subscriby-rest-api/revisions/7b538e472e9a?raw)