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. It is set per organization.

Orders

Create order takes services (the items), the cycle and an optional promoCode, which applies to the order's own invoice only. Each item names its kind in type:

An item has no quantity field, so two servers are two items, and none for the operating system, which is chosen at deployment. A plan not sold on the requested cycle is refused with BILLING_CYCLE_NOT_OFFERED.

The response carries the order, the invoiceId raised for it, the subscriptions it opened and the provisionedItems it created. On a term cycle the servers are provisioned once that invoice is paid in full; each item's provisionedId then holds the new service's id. An order's status is UNPAID, PENDING, PROCESSING, COMPLETE or CANCELLED.

HOURLY works differently. Create bare metal service places the hourly order for you and returns the service at once, and it needs the organization's billing.usage_based entitlement; without it the call answers 422 with USAGE_BILLING_DISABLED. A new organization does not have the entitlement, and Apply for Hourly Billing in the cloud console asks for it.

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 moves a subscription from ACTIVE to CANCELLATION_REQUESTED; it reads CANCELED once the cancellation has gone through.

Invoices

List invoices takes unpaid_only=true for the ones still open. An invoice's status is one of UNPAID, PARTIAL, PAID, OVERDUE, 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 returns a payment status of PENDING, SUCCEEDED, FAILED or CANCELLED. With provider_type=ACCOUNT_CREDIT it pays from the organization's credit, which is the way a script holding a key pays. method_id charges a saved card instead, but the card ids sit on the organization record, which takes a console session, so a key cannot look them up.

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 with a CREDIT_PURCHASE invoice, paid like any other.

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.