Client API: Account plan

Your account's plan (Free, Pro, Business or Enterprise), its limits and what the account uses, including what Object Storage used of its free amounts this month. Preview, order, change or cancel a plan, start the free trial, and set up the mail, SMTP Relay and Object Storage your plan includes.

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.

GET /api/v1/account/entitlements

What your plan and add-ons let your account have, and what it uses.

The answer is {plan, limits, usage, over_limit, enforced}. plan is the same object GET /api/v1/account/plan returns. limits holds every entitlement: a number (-1 for unlimited), true or false for a feature, or a word for support_level. usage holds the counts we can measure: websites (static deployments included), load balancers, and the mailboxes, mail domains, messages sent this month and storage of your included services. over_limit lists each count above its limit, [{entitlement, limit, used}]: what is over keeps working, and nothing more of it can be added. enforced is false while plans are not open on your account, and nothing is refused for a limit until it is true.

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

POST /api/v1/account/included/{kind}

Set up the mail, SMTP Relay or Object Storage your plan includes.

kind is mail, sending or storage. Each account has one included service of each kind, at no charge, sized to its plan: on Free, 5 mailboxes of 1 GB on one domain and 3,000 messages a month. Object Storage is pay as you go: the service this makes is billed like one you order, and the plan's free amounts each month (10 GB-month of storage, 1 million Class A and 10 million Class B operations on Free) cover its use. When the plan changes, the service moves with it.

Creating one passes the checks a free order passes: the challenge (turnstile_token) and a limit on how fast free services are made. The answer is the service, 201 when this created it and 200 when the account already had one. Refuses with 404 for another kind, 422 for a choice the product does not take (storage needs location_id), 422 with code out_of_stock when we cannot set the service up right now (mail is not open or has no capacity, or the region has no storage), 403 when the challenge fails, 409 when the account has another free service of the kind, 429 when free orders come too fast, and 503 when the service is not available.

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

application/json (required)

Fields of a 200 response:

GET /api/v1/account/plan

Your plan, the plans you can choose and your free trial.

plan is {key, name, source, status, renews_at, ends_at, trial_ends_at, service_id, billing_cycle, currency}. key is free, plan-pro, plan-business or plan-enterprise; source is paid, trial or free; status is active, cancelling (it ends at ends_at) or trialing.

available lists Free and each plan on sale: {key, name, prices: {monthly, annually}, currency, popular, orderable, product_id, pricing_ids, limits}. currency is the currency of every price, such as USD. A plan our sales team sells has no prices and is not orderable. limits holds the plan's own value for every entitlement, as GET /api/v1/account/entitlements writes them, before add-ons.

trial is {available, plan, ends_at, status}: whether you can start your one trial now, and the trial you had. enabled is false while plans are not open on your account; the plan routes that change something then answer 403.

pending is an order or a plan change waiting for payment, {kind, service_id, plan, name, billing_cycle, invoice_id, amount_due} with kind order or change; suspended is a plan held for an unpaid invoice, {service_id, plan, name, invoice_id, amount_due}. Both are null when there is none.

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

POST /api/v1/account/plan

Order Pro or Business, or change your plan to it.

Without a plan, this places an order the way POST /api/v1/services/order does: an invoice for the first period, paid from your credit when it covers it, and the plan starts once it is paid. promo_code takes a code's discount off that invoice; a code the order cannot use refuses it with 422, {"errors": [<sentence>], "promo": <reason>}. Ordering again while an order waits for payment answers with that order, and an order for another plan replaces it.

With an active plan, this changes it the way POST /api/v1/services/{service_ref}/change-plan does: an upgrade invoices the difference for the rest of the billing period and applies once paid; a downgrade applies now and credits the unused difference, less the last few days. Changing the plan withdraws a cancellation, and choosing the plan you have while it is set to end keeps it renewing.

Choosing the other billing period (billing_cycle of monthly or annually), with or without another plan, starts the new period today and answers with change switch. Monthly to yearly invoices the year and takes the unused days of the current month off that invoice; credit pays it when it covers it, and otherwise the plan changes once the invoice is paid. Yearly to monthly applies now: the unused days of the year, less the days a downgrade gives up, pay the first month, and the rest go to your account credit. When they do not cover the month, you pay the difference. The preview prices it first.

The answer is {service_id, invoice_id, status, change, amount_due, message}. status is payment_required (pay invoice_id), provisioning (the plan starts in a moment), changed or renewing. A running trial ends when the plan starts.

Refuses with 403 while plans are not open on your account; with 422 for Free (cancel instead), Enterprise, an unknown plan or billing, and a promo code on a plan change; with 404 for a plan not on sale with that billing; with 409 for the plan you already have, a plan our sales team set, a change of billing period while a renewal invoice is unpaid, a change while the plan is due to renew, a suspended plan and an order that is being set up.

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

application/json (required)

POST /api/v1/account/plan/cancel

Cancel your plan. The account moves to the Free plan.

Pro or Business stays until the end of the period you paid for and then ends; choosing it again with POST /api/v1/account/plan before then keeps it. A suspended plan ends now and its unpaid invoice is cancelled. A trial ends now. A plan order that was never paid is cancelled with its invoice. Nothing is deleted: what is over the Free plan's limits keeps working, and nothing more of it can be added.

The answer is {status, ends_at, message}, with status cancelling (the plan ends at ends_at), ended, trial_ended or order_cancelled. Refuses with 409 when the plan is already set to end, when an order is being set up, and when there is nothing to cancel.

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

application/json

POST /api/v1/account/plan/preview

What choosing a plan would cost now, and what it would leave over the new plan's limits. Nothing changes.

plan is free, plan-pro or plan-business, and billing_cycle is monthly or annually. promo_code prices a code on a new plan order as the order would. The answer is {plan, name, billing_cycle, change, due_now, discount, credit, currency, renews_at, renewal_amount, ends_at, over_limit, trial, promo, server_access, message}:

• change is new (an order, paid up front), upgrade (the difference for the rest of this billing period is due now), downgrade (it applies now, and the unused difference goes to your credit less the last few days), cancel (to Free, at ends_at), renew (a plan set to end keeps renewing), switch (a move between monthly and yearly billing, below) or none;
• a switch starts the new billing period today. Monthly to yearly invoices the year and takes the unused days of the current month off it, so due_now is the year less those days. Yearly to monthly applies now: the unused days of the year, less the holdback days a downgrade gives up, pay the first month, and credit is what is left for your account credit (due_now is 0). When they do not cover the month, due_now is the rest. renews_at is the end of the new period, and cycle_switch is {from, to, unused_credit, holdback_days}, null for any other change. The plan can change at the same time;
• over_limit lists each count the new plan would leave above its limit, [{entitlement, limit, used}]. Nothing is deleted: what is over keeps working, and nothing more of it can be added;
• renew_at_own_price lists the floating IPs and DDoS Shield profiles the plan pays for now beyond what the new plan pays for, [{entitlement, limit, used}]. The plan keeps paying for the oldest; the newest keep working and renew at their own price from their next renewal;
• trial is converts when the plan is the same as a running trial's or higher, ends when it is lower, and null without a trial;
• discount is what the promo code takes off the first invoice, and due_now is what is left. promo is {valid, code, message, reason, summary, duration, cycles}, or null without a code. renewal_amount is the plan's price before the code;
• server_access is null unless the plan changes who pays for Server access. Choosing Pro or Business while you hold the Server access add-on, or during a trial, gives {ends: true, credit}: the add-on ends when the plan starts and credit (a string such as "1.23") for its unused days goes to your account credit. Choosing Free while your plan or trial includes Server access gives {included_after: false, servers}: your servers virtual machines and game servers keep running and bill by use, and a new one needs the add-on;
• message says all of it in a sentence or two.

Refuses Enterprise and unknown plans or billing (422), a plan that is not on sale with that billing (404), and with 409: a plan whose terms our sales team set, a change of billing period while a renewal invoice is unpaid, a change while the plan is due to renew, and a suspended plan. A promo code on a plan change or on Free, or one the order would refuse, answers 422 {"errors": [<sentence>], "promo": <reason>} as POST /api/v1/account/plan does. A refused code counts against the budget POST /api/v1/billing/promo/validate keeps, and while that budget is spent a code answers 429 with promo rate_limited.

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

application/json (required)

POST /api/v1/account/plan/trial

Start your account's one free trial of Pro or Business.

A trial lasts 14 days, needs no card and creates no invoice. It gives the plan's limits at once and moves your included mail, SMTP Relay and Object Storage up to the plan's allowance. Buying the same plan or a higher one during the trial ends it and keeps what you have; when it runs out, the account returns to Free. We email you 4 days and 1 day before it ends, and when it ends. Nothing is deleted.

The answer (201) is {plan, trial, message}, with plan as GET /api/v1/account/plan returns it. Refuses with 403 while plans are not open on your account or when the challenge fails, 422 for a plan other than Pro or Business, 409 when the account has had its trial or has Pro or Business, and 429 after five tries in an hour.

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

application/json (required)