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.
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.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/account/referrals |
The account's referral link, the terms, and the accounts it referred |
| 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
Section titled The account's referral link, the terms, and the accounts it referredGET /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
Section titled 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
Section titled Check a promo code before ordering, without using itPOST /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
Section titled Request bodyapplication/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
Section titled 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. |