Billing

Billing cycles

A service is billed on one of five cycles: HOURLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY or ANNUALLY. Each plan prices all five under pricing.rates, where every rate has three fields:

Units of money

Amounts are integers in the currency's minor units, and the field or schema says which scale:

• Plan prices are in millicents, thousandths of a cent: priceMillicents: 150000 is 150 cents, 1.50 in the currency.
• Invoice, usage and account-credit amounts are in cents: an invoice total of 12999 is 129.99.

The currency is an ISO 4217 code, carried on each plan's pricing, each invoice and each subscription as currency. An organization is billed in one currency, and that currency cannot be changed.

Ordering services

How you buy a new server or IP block depends on its billing cycle:

Create order takes all five cycles, and an order without cycle is placed as HOURLY, so a term order always names its cycle. The two single-item calls are shorthands for an hourly order of one item: they place the same order, run the same checks and accept an Idempotency-Key the same way (Idempotency).

Hourly billing is the organization's billing.usage_based entitlement, which a new organization does not have; for now it is granted on request through support in the cloud console. Get entitlements shows whether yours has it, and an hourly request without it answers 422 USAGE_BILLING_DISABLED.

Order items

services holds one item per server or IP block, since an item has no quantity field. Each item names its kind in type, and an item without one is refused with 400 VALIDATION_ERROR:

The operating system is not part of the order: it is chosen when the server is deployed.

A server gets an IPv4 /30 and an IPv6 /120 unless its item asks for something else:

null leaves that address family off the server. A length from 24 to 29 with no IPv4 block plan behind it is refused with a 422 IPV4_PREFIX_SIZE_UNAVAILABLE detail, and an IPv6 length other than 120 with IPV6_PREFIX_SIZE_UNAVAILABLE. IPv6 ordered with IPv4 is left out when the datacenter has no IPv6 space, and the server comes up without it; ordered alone, it fails the item instead. A server with both set to null gets no network and no address, and cannot be deployed until you attach a network of your own and assign it a primary IPv4 address (Networking).

The prefixes sit on an internet access network created for that server and are billed on the server's own subscription. A baremetal item has no network field.

A publicNetworkId on an ipblock item that does not exist or belongs to another organization answers 404 ENTITY_NOT_FOUND. List service virtual networks gives a server's networks with their ids, so a block for a new server is ordered once that server exists.

Each item's plan is checked when the order is placed. An offeringId that matches no plan is a 422 VALIDATION_FAILED with an OFFERING_NOT_FOUND detail on services[<i>].offeringId, or on offeringId for the hourly shorthands. A plan out of stock in that datacenter, a datacenter without room for the requested prefix and an unknown datacenterId all answer 422 OFFERING_NOT_AVAILABLE. promoCode takes its discount off a term order's first invoice; renewals and hourly orders are not discounted. A code the platform does not know is accepted and takes nothing off.

Paying for a term order

Create order answers 201 with data.order, whose status is UNPAID, and data.invoiceId. The invoice is due on the day it is raised. It bills each server at its plan's priceMillicents for the cycle, any priced IPv4 prefix on a line of its own, tax for the organization's billing address, and the promo discount. An organization with no billing address gets 422 BILLING_ADDRESS_REQUIRED after the order has been saved; set the address in the cloud console, then send the same request with the same Idempotency-Key to raise the invoice for that saved order.

Nothing pays this invoice for you. Renewal invoices are charged on their due date, from account credit first and then the default card, but an order's first invoice waits until a payment covers it. From a script, Pay invoice with providerType=ACCOUNT_CREDIT pays it from the organization's credit; Invoices covers partial and card payments. A pay request without providerType starts a card payment that only a browser can confirm. The credit itself comes from a credit purchase, paid by card in the cloud console.

An order left unpaid is cancelled within 24 hours. Until then it holds no server: stock is checked when the order is placed and again when the paid order is provisioned.

Once the invoice reads PAID, provisioning runs in the background. Each item gets a subscription of its own on the order's cycle, and Get order shows the outcome: the item moves from PENDING to COMPLETED, its provisionedId holds the new server's id (the new prefix's id for an ipblock item), and the order moves from UNPAID to COMPLETE. List invoices gives each order invoice's orderId.

An item that cannot be provisioned reads FAILED; a server whose plan sold out between the order and the payment is one example. The order reads FAILED once provisioning has ended with at least one failed item, even when the others completed. The order does not say why an item failed, nothing retries it, a paid invoice stays paid and nothing is refunded automatically, so contact support with the order's id.

Hourly requests

Create bare metal service takes the fields of a baremetal item at the top level of the body and answers 200 with the new service, whose id is the server's id. Create IP block takes those of an ipblock item and answers 200 with the block's prefixId and the subscriptionId that bills it. Neither takes a cycle.

An hourly request that could provision nothing answers 409 PROVISIONING_FAILED, and the order it placed is kept with status FAILED. Create order with several hourly items can succeed in part: it answers 201 with invoiceId null, the subscriptions it opened, and provisionedItems, one entry per item holding its provisionedId, or success false and an errorMessage. The hours are billed afterwards, as usage.

Subscriptions

Each billed service belongs to a subscription, which keeps its cycle, lastRenewal, nextRenewal and the items it bills: bare metal servers, cloud servers and IP blocks. An item's provisionedId is the id of the service it bills, and Get subscription for a service looks the subscription up from that id.

Request cancellation answers 204 and moves a subscription from ACTIVE to CANCELLATION_REQUESTED at once. From that moment the subscription raises no renewal invoices and an hourly one stops accruing usage. The server keeps running until our staff remove it, and the subscription reads CANCELED after that. Deleting a bare metal service starts the same cancellation. An IP block ordered on its own is different: with none of its addresses assigned it is released at once, and its subscription goes straight to CANCELED.

Asking again while the cancellation is pending answers 204 again. A subscription that is already CANCELED answers 422 SUBSCRIPTION_NOT_ACTIVE, and one with an item that cannot be cancelled yet answers 422 TERMINATION_BLOCKED with nothing changed. 422 SUBSCRIPTION_CANCELLATION_INCOMPLETE means some items were cancelled before one failed; sending the request again is safe and does not repeat the finished ones.

Invoices

List invoices takes unpaidOnly=true for the ones still open: UNPAID, PARTIAL and OVERDUE. An invoice's status is one of those three, PAID, COLLECTIONS, CANCELLED or REFUNDED, and its type is STANDARD or, for a credit top-up, CREDIT_PURCHASE. Download invoice PDF returns the PDF itself rather than JSON.

Pay invoice takes a providerType of ACCOUNT_CREDIT or STRIPE and returns a payment status of PENDING, SUCCEEDED, FAILED or CANCELLED. ACCOUNT_CREDIT pays from the organization's credit, which is the way a script holding a key pays. It takes what the balance holds, up to the amount due, so a balance smaller than the invoice leaves it PARTIAL with the payment SUCCEEDED. STRIPE with a methodId charges a saved card, but the card ids sit on the organization record, which takes a console session, so a key cannot look them up.

A refused payment is a 422 whose data holds the payment result:

A card payment that needs the cardholder's confirmation (3-D Secure) returns a clientSecret, and Confirm invoice payment records the outcome after Stripe's confirmation step. That step runs in a browser with Stripe.js and our publishable key, which the API does not hand out, so card payments are made in the cloud console.

Usage in the current period

Get current usage covers the billing period in progress:

• billingPeriodStart, billingPeriodEnd and billingCycleDay, the day of the month the period turns over;
• totalAccruedCharges, what metered services have run up so far: each one's hourly rate times its billable hours in the period;
• estimatedPeriodEndCharges, the same total projected to billingPeriodEnd, counting services that are still running as if they run until then and terminated ones at what they accrued;
• activeServiceCount and terminatedServiceCount.

Account credit

Get credit balance and entries returns the organization's creditBalance, the smallest and largest amount a single purchase accepts (minPurchaseAmount, maxPurchaseAmount) and the ledger entries, all in cents. The purchase limits default to 1,000 and 1,000,000 cents. Purchase credit takes an amount and answers 201 with a CREDIT_PURCHASE invoice, paid like any other; an amount outside the limits is a 422 with a CREDIT_AMOUNT_INVALID detail on amount.

Payment methods

Cards are added in the cloud console, through Stripe, so the card number never passes through this API. Add a card starts the Stripe SetupIntent behind that form and returns its client secret, but completing it takes Stripe.js with our publishable key, which the API does not provide. Update payment method makes a saved card the default, and Delete payment method removes one.