--- title: "Get the programme" method: GET path: "/v1/projects/{project}/referral-program" tags: ["Referral Program"] --- # Get the programme `GET /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 ```bash curl https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/referral-program \ -H "Authorization: Bearer sbt_..." ``` The programme as it stands, with its commission currency's ISO code loaded. `404 RESOURCE_NOT_FOUND` while the project has none. ### Three fields that are easy to misread > **`plan_ids: []` means every plan, not no plans.** A conversion counts on every plan in the project, including plans added later. Treating it as "restricted to nothing" inverts the meaning. **`commission_period_months`** is `0` for the friend's first payment only, a number of months, or `null` for life. A `fixed` commission is always the first payment only and always reports `0`. **`commission_value` is a decimal string with four places**: `"20.0000"` for 20% of each payment, `"10.0000"` for ten of the commission currency. Parse it as a decimal, never a float. `commission_currency_id` is `null` on a percentage, which is earned in each payment's own currency. ## Path parameters - `project` string, uuid, required ## Response `200` The programme; 404 `RESOURCE_NOT_FOUND` while the project has none. - 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 - `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. - `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. - `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/59c4df91d764?raw)