# Organization API: Organizations & Members: Referrals

> The 7 Organization API operations for referrals.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/referrals/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/referrals`](#op-get-api-v1-orgs-org-slug-referrals) | List the organization's referrals and what the program has paid |
| GET | [`/api/v1/orgs/{org_slug}/referrals/codes`](#op-get-api-v1-orgs-org-slug-referrals-codes) | List referral codes, customers' and partners' |
| POST | [`/api/v1/orgs/{org_slug}/referrals/codes`](#op-post-api-v1-orgs-org-slug-referrals-codes) | Make a partner code for a customer |
| PATCH | [`/api/v1/orgs/{org_slug}/referrals/codes/{code_id}`](#op-patch-api-v1-orgs-org-slug-referrals-codes-code-id) | Stop or restart a code, or change a partner's commission or label |
| GET | [`/api/v1/orgs/{org_slug}/referrals/settings`](#op-get-api-v1-orgs-org-slug-referrals-settings) | Read the referral program's settings |
| PUT | [`/api/v1/orgs/{org_slug}/referrals/settings`](#op-put-api-v1-orgs-org-slug-referrals-settings) | Change the referral program's settings |
| POST | [`/api/v1/orgs/{org_slug}/referrals/{referral_id}/void`](#op-post-api-v1-orgs-org-slug-referrals-referral-id-void) | Void a referral that has not been paid |

### List the organization's referrals and what the program has paid {#op-get-api-v1-orgs-org-slug-referrals}

`GET /api/v1/orgs/{org_slug}/referrals`

Every referral of the organization, newest first, and the program's totals.

Needs the Admin or Owner role. A referral is one referred customer: their first paid invoice started it.
``status`` is ``qualified`` while it waits out its hold (``hold_until``), ``credited`` once the wallet credit
is paid, and ``void`` when a rule refused it (``void_reason`` says which, or holds the reason staff gave).
``referrer`` and ``referee`` name the two customers, ``code`` the code that was used and ``invoice`` the
invoice that started it. ``reward_amount`` is what the referrer is paid and ``referee_reward_amount`` the
welcome credit, both in wallet dollars (``currency``). ``count`` is how many referrals match the filters.
``totals`` covers the whole program and ignores the filters: the number of referrals in each status,
``credited_amount`` paid out so far and ``owed_amount`` for the open ones.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no | pending, qualified, credited or void. |
| `q` | query | string or null | no | Part of either customer's email address, without regard to capitals. |
| `limit` | query | integer | no | Referrals to return, newest first. At most 200. Default: `50`. |
| `offset` | query | integer | no | Referrals to skip. Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List referral codes, customers' and partners' {#op-get-api-v1-orgs-org-slug-referrals-codes}

`GET /api/v1/orgs/{org_slug}/referrals/codes`

The organization's referral codes, newest first, each with how many referrals it started.

Needs the Admin or Owner role. A ``customer`` code is made for each customer the first time they open their
referral page. A ``partner`` code is made by your team and pays ``commission_bp`` of the referred customer's
first invoice. ``referrals`` on a code is ``{total, credited, earned}``: the referrals it started, how many
were paid, and what they paid the owner in wallet dollars.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `kind` | query | string or null | no | customer or partner. |
| `active` | query | boolean or null | no | true for codes that work, false for stopped ones. |
| `q` | query | string or null | no | Part of the code, its label or the owner's email address. |
| `limit` | query | integer | no | Codes to return, newest first. At most 200. Default: `50`. |
| `offset` | query | integer | no | Codes to skip. Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Make a partner code for a customer {#op-post-api-v1-orgs-org-slug-referrals-codes}

`POST /api/v1/orgs/{org_slug}/referrals/codes`

Make a partner code that pays a share of the first invoice of every customer it brings.

Needs the Admin or Owner role. Name the owner with ``customer_id`` or ``email``: an active customer of this
organization. ``commission_bp`` (1 to 5000, 100 is 1 percent) is the share of the referred customer's first
invoice, without tax, paid into the owner's wallet once the hold has passed. ``code`` is optional: 3 to 40
letters, digits, hyphens or underscores, and without regard to capitals it must not be in use (409). Left out,
we make an 8 character code. At most 30 codes an hour. Answers 422 with ``detail`` and ``field`` for a value
that does not fit. The code is recorded in the audit log as ``referral_code.created``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | boolean or integer or string or null | no | The customer who owns the code. Give this or email. |
| `email` | string or null | no | The email address of the customer who owns the code. Give this or customer_id. |
| `code` | string or null | no | The code, 3 to 40 letters, digits, hyphens or underscores. Left out, we make an 8 character one. |
| `commission_bp` | boolean or integer or string or null | no | The share of the referred customer's first invoice, without tax, the owner is paid, in basis points: 1 to 5000 (100 is 1 percent). |
| `label` | string or null | no | A note for your team, such as the partner's name. |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Stop or restart a code, or change a partner's commission or label {#op-patch-api-v1-orgs-org-slug-referrals-codes-code-id}

`PATCH /api/v1/orgs/{org_slug}/referrals/codes/{code_id}`

Change whether a code works, a partner code's commission, or its label. The code itself never changes.

Needs the Admin or Owner role. ``active: false`` stops the code from starting new referrals; referrals it
already started still pay. ``commission_bp`` (1 to 5000) is for a partner code only: a customer's code pays
the program's reward amount. ``label`` is a note for your team, and null or an empty string removes it. Send
only what changes. Answers 404 for a code of another organization and 422 with ``detail`` and ``field`` for a
value that does not fit. A change is recorded as ``referral_code.updated`` with the values before and after.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code_id` | path | integer | yes | The code's id. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `active` | boolean or null | no | false stops the code from starting new referrals. Referrals it already has still pay. |
| `commission_bp` | boolean or integer or string or null | no | A partner code's share in basis points: 1 to 5000. |
| `label` | string or null | no | A note for your team. null or an empty string removes it. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Read the referral program's settings {#op-get-api-v1-orgs-org-slug-referrals-settings}

`GET /api/v1/orgs/{org_slug}/referrals/settings`

The referral program's settings, with the wallet currency and the limit of each number.

Needs the Admin or Owner role. The program is off until ``enabled`` is true. ``reward_amount`` is paid to
the customer who shared a code, ``referee_reward_amount`` to the customer who used it (0 for none),
``threshold_amount`` is what that customer's first paid invoice must reach without tax, ``hold_days`` how long
a qualified referral waits before it is paid, ``monthly_cap`` how many referrals one customer is paid for in
30 days, and ``block_paid_ads`` whether an order that came from a paid ad is refused. Amounts are decimal
strings in wallet dollars.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change the referral program's settings {#op-put-api-v1-orgs-org-slug-referrals-settings}

`PUT /api/v1/orgs/{org_slug}/referrals/settings`

Turn the program on or off and change its amounts, hold and limits.

Needs the Admin or Owner role. Send only the settings that change. ``reward_amount``,
``referee_reward_amount`` and ``threshold_amount`` are amounts with at most 2 decimals (the first two 0 to
1000, the threshold 0 to 10000), ``hold_days`` is 1 to 90, ``monthly_cap`` is 1 to 500, ``enabled`` and
``block_paid_ads`` are true or false. A value that does not fit, or a name that is not a setting, answers 422
with ``detail``, the sentence to show, and ``field``, the input it belongs to, and changes nothing. The answer
is the settings as ``GET`` gives them, with ``changed`` listing the keys that differ from before. A change is
recorded in the audit log as ``referrals.settings_updated`` with the keys before and after. A new amount
applies to referrals that start after the change. A referral already waiting keeps the amounts it started with.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or integer or string or null | no | true turns the program on. Nothing is made or paid while it is off. |
| `reward_amount` | boolean or string or integer or number or null | no | What a customer's own code pays the referrer, in wallet dollars: 0 to 1000 with at most 2 decimals. |
| `referee_reward_amount` | boolean or string or integer or number or null | no | A welcome credit for the customer who was referred, in wallet dollars: 0 to 1000. 0 pays none. |
| `threshold_amount` | boolean or string or integer or number or null | no | What the referred customer's first paid invoice must reach, without tax, in wallet dollars: 0 to 10000. |
| `hold_days` | boolean or integer or string or null | no | Days a qualified referral waits before it is paid: 1 to 90. |
| `monthly_cap` | boolean or integer or string or null | no | Most referrals one customer is paid for in 30 days: 1 to 500. |
| `block_paid_ads` | boolean or integer or string or null | no | true refuses a referral whose order came from a paid ad (paid search, paid social or display). |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Void a referral that has not been paid {#op-post-api-v1-orgs-org-slug-referrals-referral-id-void}

`POST /api/v1/orgs/{org_slug}/referrals/{referral_id}/void`

Void a referral so it is never paid. Only a ``pending`` or ``qualified`` referral can be voided.

Needs the Admin or Owner role. ``reason`` is required, 1 to 120 characters, and is kept as the referral's
``void_reason``. A referral that is already ``credited`` or ``void`` answers 409, and money already paid is not
taken back. Answers 404 for a referral of another organization. At most 60 an hour. Recorded in the audit log
as ``referral.voided`` with the reason.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `referral_id` | path | integer | yes | The referral's id. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no | Why the referral is void, 1 to 120 characters. It is kept with the referral. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |