Client API: Checkout

Price an order before you place it: the first invoice's lines, a promo code's discount, what is due now and what renews.

View as Markdown

Price an order before you place it: the first invoice's lines, a promo code's discount, what is due now and what renews. Nothing is written.

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
POST	`/api/v1/checkout/quote`	What an order would cost, without placing it

What an order would cost, without placing it

Section titled What an order would cost, without placing it

POST /api/v1/checkout/quote

What an order would cost, without placing it.

Send the body you would send to POST /api/v1/services/order, addons and promo_code included. The answer lists the lines of the order's first invoice, what the promo code takes off, what is due before the order starts and what renews at what price. An order that would be refused is refused here with the same status and the same sentence, so a checkout can show it before anyone pays. The quote writes nothing, and the order checks everything again.

A virtual machine or a game server takes its size from the plan, so a config that names a vCPU, memory or disk figure the plan does not have is refused with 422 and field naming it, as the order refuses it.

A promo code the order cannot use does not refuse the quote: promo says why, with valid false. A refused code counts against the same budget as POST /api/v1/billing/promo/validate.

An App Deployment body (a kind or a placement in config) is checked by the function the order calls, :func:app.deployments.order.prepare_container_config. Its lines have one line per location. On a commit each is the location's committed instances at the chosen price, and they add up to the first invoice. On pay as you go each is what an hour costs at the location's minimum instances and its price multiplier, while due_now stays the first invoice: one instance-hour at the plan's price. A static deployment runs no instance: it has no line, and nothing is due or renews for it. deployment says how the rating job will bill it: what an instance-hour costs in each location, and each allowance its kind counts against, with what the account has used of it this month and the pack that raises it.

org_slug quotes an App Deployment for that organization as the order places it, on the owner's account: the owner's plan, credit and allowances price it, and the same caller is refused the same way.

An order billed by what it uses (a virtual machine, a game server, a database, or an App Deployment of kind git, image, hybrid or static ordered on your own account) has no line for the product and nothing due now: due_now is 0.00, billing_mode is usage and the order renews nothing but its add-ons. estimate says what it is expected to cost. A server has usage: its size's hourly and monthly figures from the rate card. A web deployment has included_monthly (the free amounts every account gets each month), profiles (the monthly cost after those amounts for three sample months, idle, light and busy, each with the quantity of every meter it uses and what is billable) and assumptions (the instances, the hours they run, the region that prices data out, and in each profile's assumes the GiB of memory and vCPU of CPU each instance uses, the millions of requests it answers and the GB it sends out). The instances are the minimum of every location the order names. A static site has no instance, and the cost of its profiles is 0.00 inside the free amounts. sample repeats the light profile. paid_plan says whether the order needs Server access and the account lacks it, and deposit whether it waits for the first deposit and the minimum to deposit. The quote reports both where the order refuses them (402 and 403). paid_plan.price is the active monthly price of the Server access add-on in the catalogue.

include_paid_plan: true quotes the order with Server access added, as the order buys it: a line labelled Server access (kind addon, cycle monthly) that due_now and renews count. paid_plan keeps saying whether the account lacks it. It answers 422 as the order does: with included_by_plan while the plan already includes Server access, with already_ordered while the account holds it, and with a sentence for an order that is not a virtual machine or a game server billed by use. A body for a web order may leave product_id and pricing_id out, and its scaling.max_memory_mb (the largest memory limit the platform may grow an instance to) is checked as the order checks it.

An order for Mail Hosting, SMTP Relay, Object Storage or a floating IP that we cannot set up right now answers 422 with detail set to {"code": "out_of_stock", "message", "errors"}, before anything is charged. That is the case when mail is not open for orders or has no capacity, when the region you chose has no storage available, and when no floating IP is in stock. GET /api/v1/availability says which of these are available now.

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

Request body

Section titled Request body

application/json (required)

Field	Type	Required	Description
`product_id`	integer or null	no	The product to order. An App Deployment of kind git, image, hybrid or static, ordered on your own account, may leave it out or send 0: it is then ordered on App Deployment's usage terms. Naming a CX plan on such an order sets the memory the deployment starts with. Every other order names the product.
`pricing_id`	integer or null	no	The price of the product. Leave it out only when product_id is also left out, or names App Deployment's own product, which has one price. Virtual machines and game servers are billed by use whichever price you name.
`hostname`	string or null	no	The service's name. A Cloud Compute order uses it as the guest hostname: one name of up to 63 letters, digits and hyphens, with no dots and no hyphen at either end. Any other hostname answers 422.
`config`	object or null	no
`idempotency_key`	string or null	no	Replay key for IP orders (double-submit / multi-tab)
`turnstile_token`	string or null	no
`addons`	array of ServiceOrderAddon	no	Up to 8 products bought with this one. Cloud Compute takes Floating IP, DDoS Shield, Mail Hosting and SMTP Relay. App Deployment takes Floating IP, DDoS Shield, Snapshot Storage, Mail Hosting and SMTP Relay. Floating IP takes DDoS Shield. Mail Hosting takes SMTP Relay. App Deployment also takes extra backup slots, extra ports, extra databases, extra CPU, automatic backups and Server Management. Cloud Compute also takes automatic backups. Floating IP, DDoS Shield and Snapshot Storage go on a server, so of the App Deployment kinds only a template takes them. When the API cannot take one add-on, it refuses the whole order and creates nothing.
`addons[].product_id`	integer	yes	The add-on product.
`addons[].pricing_id`	integer or null	no	One of the add-on's active prices. Leave it out to take the price with the parent's billing cycle, else the monthly price, else the first active price.
`addons[].quantity`	integer	no	How many to order. Each floating IP becomes its own service. A capacity add-on sold per unit, such as Extra Port, becomes one service that holds its quantity, up to 20 units. Every other add-on takes 1.
`addons[].config`	object or null	no	The add-on's own config, as an order for that product on its own takes it. A floating IP comes from the parent's location unless config.pool_id names a pool. A DDoS Shield add-on takes profile_name (up to 40 characters), protection_mode, default_action, per_source_pps and aggregate_pps. The order sets the addresses it protects, so the API refuses ip_service_ids.
`promo_code`	string or null	no	A promo code. Its discount comes off the product ordered on the first invoice, and off later invoices when the code repeats. A code the order cannot use refuses the order with 422.
`include_paid_plan`	boolean	no	Buy Server access with this order. A virtual machine or a game server needs it, and a Free account has none, so without this the order answers 402 `paid_plan_required`. With `true` the order adds Server access (the `addon-compute-paid` add-on, billed monthly at its current price) to the same first invoice. The server starts when that invoice is paid, at once when your credit covers it. The order answers 422 with `included_by_plan` when your plan already includes Server access, with `already_ordered` when your account already holds it, and with a sentence when the order is not a virtual machine or a game server billed by use.
`org_slug`	string or null	no	Order an App Deployment for this organization instead of your own account. You must be the organization's owner or an admin. The deployment belongs to the organization, and the service goes on the owner's account, which pays for it. Only an App Deployment can be ordered this way.

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
`lines`	array of QuoteLine	The lines of the order's first invoice. An App Deployment has one line per location: on a commit its instances at the chosen price, on pay as you go an estimate of each hour at its minimum instances, charged from credit by the hour. A static deployment has none: it runs no instance, so it is ordered at 0 and billed only for use past its allowances. An order billed by use has no line for the product, only for its add-ons.
`lines[].label`	string
`lines[].amount`	string	What the first invoice charges for this line.
`lines[].cycle`	string	The billing cycle it renews on, or one_time for a setup fee.
`lines[].kind`	string	recurring for the product ordered, setup for its setup fee, addon for the rest.
`subtotal`	string	The lines added up. On pay as you go it holds each location's hourly estimate, not what is due now.
`discount`	string	What the promo code takes off the first invoice.
`due_now`	string	What the order asks you to pay before it starts: the first invoice less the discount, or 0.00 when the order is billed at its first renewal instead. An App Deployment on pay as you go asks for one hour of one instance at the plan's price, as every hourly order does; a static deployment asks for nothing.
`requires_payment`	boolean	Whether the order waits for its first invoice to be paid.
`currency`	string
`renews`	array of QuoteRenewal	What renews, and at what price.
`renews[].label`	string
`renews[].amount`	string	What each renewal charges, after a promo code that repeats.
`renews[].cycle`	string
`promo`	QuotePromo or null	Null when the order names no promo code.
`promo.valid`	boolean
`promo.code`	string or null
`promo.message`	string
`promo.reason`	string or null	Why the code was refused: unknown, inactive, not_yet, expired, exhausted, already_used, first_order, wrong_product, nothing_off, rate_limited or unavailable.
`promo.summary`	string or null
`promo.duration`	string or null
`promo.cycles`	integer or null	How many invoices the code discounts, when it repeats a set number of times.
`deployment`	QuoteDeployment or null	How an App Deployment order is billed; null for any other order.
`deployment.kind`	string
`deployment.billing_mode`	string or null	usage when the order is billed by what it uses. Otherwise payg or commit, as the rating job bills it; null for a template in one location, which App Deployment bills at its plan's price as it always has.
`deployment.overage`	string	block stops use past an allowance; allow bills it per unit, up to the spend limit.
`deployment.spend_limit`	string or null
`deployment.max_memory_mb`	integer or null	The largest memory limit, in MB, the order sets for an instance on usage terms. Null when the order names none, and the platform's default (4096) applies.
`deployment.locations`	array of QuoteLocation	Where it runs; empty for a static deployment, which the edge serves.
`deployment.allowances`	array of QuoteAllowance	The metered allowances its kind uses, each shared by the account's deployments.
`billing_mode`	string or null	usage when the order is billed by what it uses; null for an order at a flat price.
`estimate`	QuoteEstimate or null	What an order billed by use is expected to cost; null for an order at a flat price.
`estimate.basis`	string	server for a virtual machine, a game server or a database, priced by its size. web for an App Deployment, priced by what it uses.
`estimate.usage`	object or null	For a server: what the size costs per hour and per month with no CPU in use (hourly_idle, monthly_idle), with the CPU at 10% of its vCPUs (hourly_typical, monthly_typical) and with every vCPU busy all hour (hourly_max, monthly_max), and what its disk costs alone (disk_monthly).
`estimate.included_monthly`	Included Monthly	The free amounts each month, by meter. A web deployment gets them on every account; a server gets them with Server access.
`estimate.assumptions`	QuoteAssumptions or null	For a web deployment: what the profiles assume.
`estimate.profiles`	array of QuoteProfile or null	For a web deployment: its monthly cost after the free amounts for three sample months, idle, light and busy, worked from the rate card. 0.00 for a static site inside the free amounts.
`estimate.sample`	QuoteSample or null	For a web deployment: the light profile, as an older client reads it.
`paid_plan`	QuotePaidPlan or null	Whether the order needs Server access; null for an order at a flat price.
`paid_plan.required`	boolean	True when this order needs Server access and the account does not have it. The order is refused with 402 unless it sends `include_paid_plan`, which adds a `Server access` line.
`paid_plan.price`	string	What Server access costs a month: the active monthly price of its catalogue product.
`paid_plan.addon_slug`	string	The catalogue slug of the Server access add-on.
`deposit`	QuoteDeposit or null	Whether the order waits for the first deposit; null for an order at a flat price.
`deposit.required`	boolean	True when the order runs an instance on a prepaid account that has not made its first deposit. The order is refused with 403 until it has. An account billed by invoice needs none.
`deposit.minimum`	string	The first deposit, which stays in the account as credit.