# Client API: Promotions

> Check a promo code before you order, and read your referral link, its terms and the accounts that signed up with it.

Source: https://www.coritan.com/docs/api/reference/client/promotions/

Check a promo code before you order, and read your referral link, its terms and the accounts that signed up with it.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/account/referrals`](#op-get-api-v1-account-referrals) | The account's referral link, the terms, and the accounts it referred |
| POST | [`/api/v1/billing/promo/validate`](#op-post-api-v1-billing-promo-validate) | Check a promo code before ordering, without using it |

### The account's referral link, the terms, and the accounts it referred {#op-get-api-v1-account-referrals}

`GET /api/v1/account/referrals`

The account's referral link, the terms, and the accounts it referred.

The code behind the link is made on the first request. Anyone who signs up
through ``link`` is linked to this account; once their paid invoices reach
``threshold``, both accounts get ``credit_amount`` on their credit balance.
``referred`` lists up to 200 accounts, newest first, with addresses masked
(``j***@g***.com``) and a ``status``: ``pending`` until the threshold,
then ``credited``, ``qualified`` (the threshold was met while the credit
was zero) or ``void`` (the two accounts share a payment method, or one of
them closed). ``link`` is null while referrals are switched off.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type | Description |
| --- | --- | --- |
| `enabled` | boolean |  |
| `code` | string or null |  |
| `link` | string or null | The sign-up link to share; null while referrals are off. |
| `credit_amount` | string | What each account gets once a referral qualifies. |
| `threshold` | string | What the referred account must pay in invoices first. |
| `currency` | string |  |
| `referred` | array of ReferredAccount |  |
| `referred[].email_masked` | string |  |
| `referred[].status` | string | pending, qualified, credited or void |
| `referred[].created_at` | string (date-time) or null |  |
| `referred[].credited_at` | string (date-time) or null |  |
| `referred_total` | integer |  |
| `credited` | integer |  |
| `earned` | string | Credit this account has earned from its referrals. |

### Check a promo code before ordering, without using it {#op-post-api-v1-billing-promo-validate}

`POST /api/v1/billing/promo/validate`

Check a promo code before ordering, without using it.

With ``product_id`` the answer prices the code against that product's
first invoice and renewals, at ``pricing_id`` or the product's cheapest
active pricing tier. Without it, only the code itself is checked: switched
on, inside its dates, not used up, not already used by this account and,
for a first-order code, no earlier order. The order checks everything again
(``promo_code`` on ``POST /api/v1/services/order``).

A refused code answers 200 with ``valid: false``, a sentence in
``message`` and one of the ``reason`` words. 404 for a product or pricing
tier that does not exist, 422 for ``pricing_id`` without ``product_id``,
and 429 after 30 checks from one account in ten minutes.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | The promo code, in any case. |
| `product_id` | integer or null | no | The product about to be ordered. Without it only the code itself is checked. |
| `pricing_id` | integer or null | no | The product's pricing tier; its cheapest active tier when left out. Needs product_id. |

#### Responses

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

Fields of a `200` response:

| Field | Type | Description |
| --- | --- | --- |
| `valid` | boolean |  |
| `code` | string or null |  |
| `message` | string | A sentence to show under the code field. |
| `reason` | string or null | Why a code was refused: unknown, inactive, not_yet, expired, exhausted, already_used, first_order, wrong_product or nothing_off. |
| `description` | string or null |  |
| `discount_preview` | PromoPreview or null |  |
| `discount_preview.summary` | string | What the code does, such as "10% off the first 3 invoices". |
| `discount_preview.kind` | string | percent or fixed |
| `discount_preview.amount` | string | The percentage, or the fixed amount in currency. |
| `discount_preview.currency` | string |  |
| `discount_preview.duration` | string | once, repeating or forever |
| `discount_preview.cycles` | integer or null | Invoices the code discounts in all; null for every invoice. |
| `discount_preview.product_id` | integer or null |  |
| `discount_preview.pricing_id` | integer or null |  |
| `discount_preview.price` | string or null | The pricing tier's price before the discount. |
| `discount_preview.discount` | string or null | What the code takes off the first invoice. |
| `discount_preview.renewal_discount` | string or null | What it takes off each renewal it covers. |