Billing and usage

We bill packages through orders, accounts, wallets, and invoices. This page covers the public customer billing operations. See shared conventions for authentication, pagination, and errors.

Monetary amounts use micro-USD. One US dollar is 1000000 micro-USD. Identifiers are strings, including numeric identifiers.

For user-scoped routes, use @me or your own user ID as uid. Staff can address another user. Reads of individual invoices, payments, and payment methods require their account owner or staff. Workspace orders and subjects require workspace membership to read. Placing or cancelling an order requires the workspace admin role. Approving an order requires its workspace owner or staff. Cancelling a delivered subject or moving its renewal day requires its account owner or staff.

All operations below return 200 OK, including gateway webhook ingestion and commands that start payment processing. They do not return a workflow envelope. A pending payment still needs gateway settlement.

Each paginated endpoint accepts the optional limit, page, sort, dir, after, and before query parameters from pagination. Its response has items, total, limit, page, has_next, has_previous, and optional nullable after and before cursors. Response field tables mark required properties and show null wherever accepted.

Catalog

List packages

GET/v1/packagesList packages

Keyset-paginated listing of the packages on sale, newest first. Each item carries its offers, its rate card and its cheapest price, the same as the package detail.

Query parameters

Name	Type	Required	Description
`q`	string	no	Quick search by package code or name
`resource_kind`	string[]	no	Kinds to filter Values: `SERVER`, `IP_ADDRESS`.
`charge_basis`	string[]	no	Charge bases to filter Values: `FIXED`, `METERED`.

Supports pagination.

Returns 200 OK with a paged envelope of PackageDetailResponse objects.

Get a package

GET/v1/packages/{code}Get a package

Returns a package by code with its offers, its rate card and its cheapest price.

Path parameters

Name	Type	Required	Description
`code`	string	yes	Package code

Returns 200 OK with PackageDetailResponse.

Errors

404: No package with that code

List a package's moves

GET/v1/packages/{code}/transitionsList a package's moves

Keyset-paginated listing of the packages a subject on this package may upgrade or downgrade to, newest first. Each item carries its direction and the target package in the same shape as a package list item. A package with no offered moves returns an empty page. Moving to the subject's own package, to choose new values for its open fields, is always possible and is not listed.

Path parameters

Name	Type	Required	Description
`code`	string	yes	Package code

Query parameters

Name	Type	Required	Description
`direction`	string[]	no	Directions to filter Values: `UPGRADE`, `DOWNGRADE`.

Supports pagination.

Returns 200 OK with a paged envelope of PackageTransitionResponse objects.

Errors

404: No package with that code

Get a rate card

GET/v1/rate-cards/{code}Get a rate card

Returns a rate card by code with its priced parts.

Path parameters

Name	Type	Required	Description
`code`	string	yes	Rate card code

Returns 200 OK with RateCardDetailResponse.

Errors

404: No rate card with that code

Orders

Choose a package and inspect its pinned and open fields before ordering. The example assumes vps-small exists and needs no additional open-field values. Supply every required open field from its current catalog offer. A server purchase also needs a template or backup image. An upgrade accepts one item and rejects provisioning properties.

Get an order

GET/v1/orders/{oid}Get an order

Returns an order with its items and their part lines.

Path parameters

Name	Type	Required	Description
`oid`	string	yes	Order id

Returns 200 OK with OrderDetailResponse.

Errors

403: Not a member of the order's workspace
404: No order with that id

Approve an order

POST/v1/orders/{oid}/approveApprove an order

Approves an order in AWAITING_APPROVAL and collects it from the workspace owner's account. collection tells if a stored payment method is being charged or if a checkout is necessary for the remaining amount.

Path parameters

Name	Type	Required	Description
`oid`	string	yes	Order id

Returns 200 OK with CreateOrderResponse.

Errors

403: Not the owner of the order's workspace
404: No order with that id
409: The order is not awaiting approval

Cancel an order

POST/v1/orders/{oid}/cancelCancel an order

Cancels a DRAFT, AWAITING_APPROVAL or AWAITING_PAYMENT order, voids its invoice and returns the wallet credit paid toward it. Refused while a payment for the invoice waits for confirmation and after the invoice is paid. Cancelling a cancelled order changes nothing.

Path parameters

Name	Type	Required	Description
`oid`	string	yes	Order id

Returns 200 OK with OrderView.

Errors

403: Not an admin of the order's workspace
404: No order with that id
409: The order cannot be cancelled in its current state

List a workspace's orders

GET/v1/workspaces/{wid}/ordersList a workspace's orders

Keyset-paginated orders placed in the given workspace, newest first. Requires workspace membership.

Path parameters

Name	Type	Required	Description
`wid`	string	yes	Workspace id

Query parameters

Name	Type	Required	Description
`id`	string[]	no	Order ids to filter
`account_id`	string[]	no	Account ids to filter
`user`	string[]	no	Panel user ids of the paying account to filter
`workspace_id`	string[]	no	Workspace ids to filter
`status`	string[]	no	Statuses to filter Values: `DRAFT`, `AWAITING_APPROVAL`, `AWAITING_PAYMENT`, `GREEN`, `FULFILLED`, `FAILED`, `CANCELLED`.
`kind`	string[]	no	Kinds to filter Values: `PURCHASE`, `UPGRADE`, `ADJUST`.

Supports pagination.

Returns 200 OK with a paged envelope of OrderView objects.

Errors

403: Not a member of the workspace

Place an order

POST/v1/workspaces/{wid}/ordersPlace an order

Prices one or more packages and places the order. For PREPAID fixed packages, the order raises one invoice for the first cycle and pays it from the wallet first. collection tells if a stored payment method is being charged or if a checkout is necessary for the remaining amount. Paying the invoice releases the order for provisioning. A POSTPAID or metered-only order collects nothing up front, releases immediately and bills in arrears. Servers count against the workspace quota. The order bills the workspace owner's account and requires the workspace admin role. When the workspace requires order approval, an order from a member other than the owner stays in AWAITING_APPROVAL and collects nothing until the owner approves it.

items must contain at least one item. Use PURCHASE for new resources and UPGRADE for an existing subject. ADJUST is also present in the schema enum. The current implementation routes non-UPGRADE requests through purchase handling.

Path parameters

Name	Type	Required	Description
`wid`	string	yes	Workspace id the order is placed in

Request body

Field	Type	Required	Description
`idempotency_key`	string or null	no	Optional idempotency key. A replay returns the original order
`items`	CreateOrderItemRequest[]	yes	The packages being ordered, one subject each
`kind`	string	yes	PURCHASE provisions new subjects. UPGRADE changes an existing one Values: `PURCHASE`, `UPGRADE`, `ADJUST`.
`payment_mode`	string or null	no	Payment mode for fixed packages in a purchase. PREPAID pays the first cycle now. POSTPAID bills each cycle on the monthly invoice and requires consolidated billing on the workspace. Default is PREPAID. Metered packages always bill for usage. Values: `PREPAID`, `POSTPAID`.
`renewal`	string or null	no	When prepaid fixed packages renew. TODAY: the first cycle starts now. MONTHLY_DATE: the first period is one full cycle plus the days until the account's monthly date, and the order charges for the extra days. If the account has no monthly date, MONTHLY_DATE is the same as TODAY. Default is TODAY. Values: `TODAY`, `MONTHLY_DATE`.

json

{
  "kind": "PURCHASE",
  "items": [
    {
      "package_code": "vps-small",
      "resource_name": "web-01",
      "properties": {
        "kind": "SERVER",
        "image": "1447636552321908736"
      }
    }
  ]
}

Returns 200 OK with CreateOrderResponse.

Errors

402: Server quota exceeded, or the wallet balance is too low for a metered package
403: Not an admin of the target workspace, or POSTPAID is not enabled for the owner
404: Unknown workspace or package

Accounts and wallets

Get a user's billing account

GET/v1/users/{uid}/accountGet a user's billing account

Returns the user's billing account and its billing terms.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Returns 200 OK with AccountView.

Errors

404: No account for that user

Move the account's monthly date

POST/v1/users/{uid}/account/monthly-dateMove the account's monthly date

Sets the day of the month for the monthly invoice and for MONTHLY_DATE renewals. If the account has a monthly invoice, the usage and charges to date are invoiced now, and the next monthly invoice moves to the first date on the new day that is on or after its current date. Prepaid subjects keep their renewal days. move each subject to align it.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Request body

Field	Type	Required	Description
`day`	integer or null	yes	New day of the month. In shorter months the last day of the month applies. Minimum: `1`. Maximum: `31`.

json

{
  "day": 15
}

Returns 200 OK with AccountView.

Errors

400: No day, or a day outside 1-31
403: Not the account's user
404: No account for that user

Get a user's wallet balance

GET/v1/users/{uid}/walletGet a user's wallet balance

Returns the wallet and its current balance for the given user.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Returns 200 OK with WalletView.

Errors

404: No wallet for that user

List a user's wallet movements

GET/v1/users/{uid}/wallet/movementsList a user's wallet movements

Keyset-paginated ledger movements for the user's wallet, newest first.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Query parameters

Name	Type	Required	Description
`q`	string	no	Quick search by reference, group reference, or entry id
`id`	string[]	no	Ledger entry ids to filter
`type`	string[]	no	Movement types to filter Values: `TOPUP`, `USAGE_CHARGE`, `FIXED_CHARGE`, `INVOICE_SETTLEMENT`, `REFUND`, `ADJUSTMENT`, `COUPON`, `EXPIRY`, `CANCEL_REFUND`, `REPRICE_REFUND`.
`invoice_id`	string[]	no	Invoice ids to filter
`subject_id`	string[]	no	Subject ids to filter
`actor`	string[]	no	Acting user ids to filter
`reference`	string	no	Reference to match
`group_ref`	string	no	Group reference to match
`min_amount`	integer	no	Minimum amount in micro-USD (inclusive, signed)
`max_amount`	integer	no	Maximum amount in micro-USD (inclusive, signed)
`created_after`	string	no	Created at or after this instant (ISO-8601) ISO-8601 date-time.
`created_before`	string	no	Created at or before this instant (ISO-8601) ISO-8601 date-time.

Supports pagination.

Returns 200 OK with a paged envelope of LedgerEntryView objects.

Errors

404: No wallet for that user

Coupons

Redeem a coupon

POST/v1/users/{uid}/coupons/redeemRedeem a coupon

Mints the coupon's credit into the user's wallet. A coupon redeems once per user, and a coupon with no uses remaining is rejected.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Request body

Field	Type	Required	Description
`code`	string	yes	Coupon code Minimum length: `1`.

json

{
  "code": "WELCOME"
}

Returns 200 OK with RedeemCouponResponse.

Errors

404: No such coupon code, or no account for that user
409: Already redeemed by this user, or no uses remaining

List a user's coupon redemptions

GET/v1/users/{uid}/coupons/redemptionsList a user's coupon redemptions

Keyset-paginated coupons the user redeemed, newest first.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Supports pagination.

Returns 200 OK with a paged envelope of CouponRedemptionView objects.

Errors

404: No account for that user

Check whether a coupon can be redeemed

GET/v1/users/{uid}/coupons/validateCheck whether a coupon can be redeemed

Reports whether the user can redeem a code and what redeeming it would grant, without redeeming it. An unknown code is reported as invalid, not as an error.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Query parameters

Name	Type	Required	Description
`code`	string	yes	Coupon code

Returns 200 OK with CouponValidity.

Invoices

Get a rendered invoice

GET/v1/invoices/{invoice_id}Get a rendered invoice

Returns an invoice with its line items.

Path parameters

Name	Type	Required	Description
`invoice_id`	string	yes	Invoice id

Returns 200 OK with InvoiceRenderResponse.

Errors

404: No invoice with that id

List a user's invoices

GET/v1/users/{uid}/invoicesList a user's invoices

Keyset-paginated invoices for the given user, newest first.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Query parameters

Name	Type	Required	Description
`q`	string	no	Quick search by user id or invoice number
`id`	string[]	no	Invoice ids to filter
`account_id`	string[]	no	Account ids to filter
`user`	string[]	no	User ids to filter
`subject_id`	string[]	no	Subject ids with a line on the invoice
`status`	string[]	no	Statuses to filter Values: `DRAFT`, `OPEN`, `PAID`, `VOID`, `UNCOLLECTIBLE`.
`kind`	string[]	no	Kinds to filter Values: `CONSOLIDATED`, `TOPUP`, `ORDER`.
`number`	string	no	Invoice number to match
`currency`	string	no	Currency code to filter, e.g. USD
`min_total`	integer	no	Minimum invoice total in micro-USD (inclusive)
`max_total`	integer	no	Maximum invoice total in micro-USD (inclusive)
`outstanding`	boolean	no	Only open invoices with a positive amount due
`created_after`	string	no	Created at or after this instant (ISO-8601) ISO-8601 date-time.
`created_before`	string	no	Created at or before this instant (ISO-8601) ISO-8601 date-time.
`issued_after`	string	no	Issued at or after this instant (ISO-8601) ISO-8601 date-time.
`issued_before`	string	no	Issued at or before this instant (ISO-8601) ISO-8601 date-time.
`due_after`	string	no	Due at or after this instant (ISO-8601) ISO-8601 date-time.
`due_before`	string	no	Due at or before this instant (ISO-8601) ISO-8601 date-time.

Supports pagination.

Returns 200 OK with a paged envelope of InvoiceView objects.

Payments

Get the client payment configuration

GET/v1/payments/configGet the client payment configuration

Returns the browser configuration of each available gateway, keyed by gateway name, e.g. {"STRIPE": {"publishable_key": "pk_live_..."}}. An unavailable gateway is not in the object. An empty object means that no gateway accepts payments in the browser.

Returns 200 OK with object of GatewayClientConfig.

Get a payment

GET/v1/payments/{pid}Get a payment

Returns a payment by id.

Path parameters

Name	Type	Required	Description
`pid`	string	yes	Payment id

Returns 200 OK with PaymentView.

Errors

404: No payment with that id

List a user's payments

GET/v1/users/{uid}/paymentsList a user's payments

Keyset-paginated payments for the given user, newest first.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Query parameters

Name	Type	Required	Description
`q`	string	no	Quick search by user id or gateway reference
`id`	string[]	no	Payment ids to filter
`account_id`	string[]	no	Account ids to filter
`user`	string[]	no	User ids to filter
`invoice_id`	string[]	no	Invoice ids to filter
`payment_method_id`	string[]	no	Payment method ids to filter
`gateway`	string[]	no	Gateways to filter Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`direction`	string[]	no	Directions to filter Values: `INBOUND`, `REFUND`.
`status`	string[]	no	Statuses to filter Values: `PENDING`, `SUCCEEDED`, `FAILED`, `REFUNDED`.
`gateway_ref`	string	no	Gateway reference to match
`currency`	string	no	Currency code to filter, e.g. USD
`min_amount`	integer	no	Minimum amount in micro-USD (inclusive)
`max_amount`	integer	no	Maximum amount in micro-USD (inclusive)
`created_after`	string	no	Created at or after this instant (ISO-8601) ISO-8601 date-time.
`created_before`	string	no	Created at or before this instant (ISO-8601) ISO-8601 date-time.
`captured_after`	string	no	Captured at or after this instant (ISO-8601) ISO-8601 date-time.
`captured_before`	string	no	Captured at or before this instant (ISO-8601) ISO-8601 date-time.

Supports pagination.

Returns 200 OK with a paged envelope of PaymentView objects.

Open a checkout

POST/v1/users/{uid}/payments/checkoutOpen a checkout

Opens a checkout session for the customer to pay an invoice, or to fund the wallet when no invoice is given. Returns a client secret to mount in the browser. The payment stays pending until the gateway confirms settlement, which is immediate for a card but can take days for a bank transfer or direct debit. whatever the customer pays with is stored for future charges when it can be. Resumes the session already collecting an invoice rather than opening a second.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Request body

Field	Type	Required	Description
`amount`	integer or null	no	Amount to fund the wallet by, micro-USD, between $20 and $500. Required when no invoice is supplied, and ignored when one is, since the invoice sets the amount Minimum: `20000000`. Maximum: `500000000`.
`gateway`	string	yes	Gateway hosting the checkout Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`invoice_id`	string or null	no	Invoice to collect. Null funds the wallet by the amount below

json

{
  "gateway": "STRIPE",
  "amount": 25000000
}

Returns 200 OK with CheckoutResponse.

Errors

400: A wallet funding amount outside $20 to $500
404: No account or wallet for that user, or no such invoice
409: The invoice is not open, already paid, or has another payment in flight

Top up a wallet from the default payment method

POST/v1/users/{uid}/payments/topupTop up a wallet from the default payment method

Records a pending charge against the stored method the account pays with and settles it asynchronously. on success it funds the wallet with a TOPUP lot, settling a tied invoice or issuing a TOPUP receipt. Requires a stored method: to pay with a new one, open a checkout instead. Idempotent on the supplied key. Returns the pending payment.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Request body

Field	Type	Required	Description
`amount`	integer	yes	Amount to charge, micro-USD, between $20 and $500 Minimum: `20000000`. Maximum: `500000000`.
`idempotency_key`	string or null	no	Key that makes a replay return the existing payment rather than charging again
`invoice_id`	string or null	no	Invoice this top-up settles, if any. Null issues a TOPUP receipt instead

json

{
  "amount": 25000000,
  "idempotency_key": "topup-1042-a1"
}

Returns 200 OK with PaymentView.

Errors

400: The amount is outside $20 to $500
404: No account or wallet for that user, or no such invoice
409: No stored default payment method, or the invoice is not collectible

Payment methods

Get a payment method

GET/v1/payment-methods/{pmid}Get a payment method

Returns a stored payment method by id.

Path parameters

Name	Type	Required	Description
`pmid`	string	yes	Payment method id

Returns 200 OK with PaymentMethodView.

Errors

404: No payment method with that id

Delete a payment method

DELETE/v1/payment-methods/{pmid}Delete a payment method

Removes a stored payment method and releases it at its gateway. Deleting the default promotes the newest remaining method in its place, so an account with any method left always has one to charge.

Path parameters

Name	Type	Required	Description
`pmid`	string	yes	Payment method id

Returns 200 OK with an empty body.

Errors

404: No payment method with that id

Set a method as default

POST/v1/payment-methods/{pmid}/defaultSet a method as default

Makes this method the account's default, unsetting any prior default in the same transaction. A no-op if it is already the default.

Path parameters

Name	Type	Required	Description
`pmid`	string	yes	Payment method id

Returns 200 OK with PaymentMethodView.

Errors

404: No payment method with that id

List a user's payment methods

GET/v1/users/{uid}/payment-methodsList a user's payment methods

Keyset-paginated stored payment methods for the given user, newest first. Exactly one carries is_default, the method charged when no one is present.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Query parameters

Name	Type	Required	Description
`q`	string	no	Quick search by user id, card brand, or last four
`id`	string[]	no	Payment method ids to filter
`account_id`	string[]	no	Account ids to filter
`user`	string[]	no	User ids to filter
`gateway`	string[]	no	Gateways to filter Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`brand`	string	no	Card brand to match, e.g. visa
`last4`	string	no	Card last four to match
`is_default`	boolean	no	Only the account's default method
`created_after`	string	no	Created at or after this instant (ISO-8601) ISO-8601 date-time.
`created_before`	string	no	Created at or before this instant (ISO-8601) ISO-8601 date-time.

Supports pagination.

Returns 200 OK with a paged envelope of PaymentMethodView objects.

Confirm a stored method

POST/v1/users/{uid}/payment-methods/confirmConfirm a stored method

Saves the method a completed checkout stored, so it is available immediately rather than once the gateway notifies us. Repeating it returns the same method. Responds with no content when the checkout stored nothing, which is the case for methods that cannot be charged later.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Request body

Field	Type	Required	Description
`gateway`	string	yes	Gateway that hosted the checkout Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`session_ref`	string	yes	Session reference returned when the checkout was opened Minimum length: `1`.

json

{
  "gateway": "STRIPE",
  "session_ref": "cs_test_a1B2c3D4e5"
}

Returns 200 OK with PaymentMethodView.

The response body is empty when the checkout stored no reusable method.

Errors

404: No account for that user, or the checkout belongs to another

Open a checkout to store a method

POST/v1/users/{uid}/payment-methods/setupOpen a checkout to store a method

Opens a checkout that stores a payment method without collecting money. Returns a client secret to mount in the browser. only methods that can be charged later are offered.

Path parameters

Name	Type	Required	Description
`uid`	string	yes	User id, or @me for the current user

Request body

Field	Type	Required	Description
`gateway`	string	yes	Gateway that will hold the method Values: `STRIPE`, `PAYPAL`, `MANUAL`.

json

{
  "gateway": "STRIPE"
}

Returns 200 OK with CheckoutResponse.

Errors

404: No account for that user
409: A concurrent request is already setting up this gateway

Billing subjects and usage

Get a subject

GET/v1/subjects/{sid}Get a subject

Returns a subject with its full spec and the priced fields behind its price.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Returns 200 OK with SubjectDetailResponse.

Errors

403: Not a member of the subject's workspace
404: No subject with that id

Cancel a purchase

POST/v1/subjects/{sid}/cancelCancel a purchase

Terminates a delivered subject, stopping its billing. A fixed-prepaid subject refunds the unused part of the cycle to the wallet when the account is set up for it. A cycle paid before it starts is refunded in full, and an unpaid renewal is removed from its invoice. A fixed-postpaid one posts its final partial cycle on the next bill, and a metered one charges accrued usage up to now. A purchase that has not been delivered yet is cancelled on its order instead. Cancelling an already cancelled purchase is a no-op.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Returns 200 OK with SubjectView.

Errors

404: No subject with that id, or no account or wallet behind it

Quote cancelling a subject

GET/v1/subjects/{sid}/cancel-quoteQuote cancelling a subject

Returns the wallet refund that a cancel of the subject gives at this time, and the reason. The refund is prorated by the hour, so a cancel in the same hour gives the same amount.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Returns 200 OK with CancelQuoteResponse.

Errors

403: Not a member of the subject's workspace
404: No subject with that id
409: The subject is already terminated

Move a subject's renewal day

POST/v1/subjects/{sid}/renewal-dayMove a subject's renewal day

Moves the renewal of a paid-up prepaid subject forward to a day of the month. The default is the account's monthly date. The renewal only moves later, and the added days are charged at the subject's price. If the wallet cannot pay, an invoice is created and the renewal moves when it is paid.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Request body

Field	Type	Required	Description
`day`	integer or null	no	Day of the month to renew on. In shorter months the last day of the month applies. Defaults to the account's monthly date. Minimum: `1`. Maximum: `31`.

json

{
  "day": 15
}

Returns 200 OK with RenewalDayResponse.

Errors

400: Not a prepaid subject, a day outside 1-31, or no day while the account has no monthly date
403: Not the subject's owner
404: No subject with that id
409: The subject is not active, not paid up, has a renewal on an unpaid invoice, or already has a move awaiting payment

Quote moving a subject's renewal day

GET/v1/subjects/{sid}/renewal-day-quoteQuote moving a subject's renewal day

Returns the renewal of a prepaid subject after a move forward to a day of the month, and the current charge for the added days.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Query parameters

Name	Type	Required	Description
`day`	integer	no	Day of the month to renew on. Defaults to the account's monthly date

Returns 200 OK with RenewalDayQuoteResponse.

Errors

400: Not a prepaid subject, a day outside 1-31, or no day while the account has no monthly date
403: Not a member of the subject's workspace
404: No subject with that id
409: The subject is not active, not paid up, or has a renewal on an unpaid invoice

List a subject's moves

GET/v1/subjects/{sid}/transitionsList a subject's moves

Keyset-paginated listing of the upgrades and downgrades that the subject's current package offers. Each move keeps the subject's current values in the target's open fields and shows the price and prorated amount that an upgrade order bills. A move that the subject cannot make has eligible false and the reason that the order returns. A change to the open fields of the current package is not listed. use an upgrade order to the same package.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Query parameters

Name	Type	Required	Description
`direction`	string[]	no	Directions to filter Values: `UPGRADE`, `DOWNGRADE`.

Supports pagination.

Returns 200 OK with a paged envelope of SubjectTransitionResponse objects.

Errors

403: Not a member of the subject's workspace
404: No subject with that id

List a subject's usage

GET/v1/subjects/{sid}/usageList a subject's usage

Keyset-paginated hourly metered usage for a subject, newest first. Empty for a subject billed a fixed price per cycle.

Path parameters

Name	Type	Required	Description
`sid`	string	yes	Subject id

Supports pagination.

Returns 200 OK with a paged envelope of UsageRecordView objects.

Errors

403: Not a member of the subject's workspace
404: No subject with that id

List a workspace's subjects

GET/v1/workspaces/{wid}/subjectsList a workspace's subjects

Keyset-paginated services bought in the workspace, newest first, with their price, cycle, next renewal and state.

Path parameters

Name	Type	Required	Description
`wid`	string	yes	Workspace id

Query parameters

Name	Type	Required	Description
`q`	string	no	Quick search by resource name, or an exact subject id
`id`	string[]	no	Subject ids to filter
`state`	string[]	no	States to filter Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`.
`resource_kind`	string[]	no	Kinds to filter Values: `SERVER`, `IP_ADDRESS`.
`package_code`	string[]	no	Package SKUs to filter
`charge_basis`	string[]	no	Charge bases to filter Values: `FIXED`, `METERED`.

Supports pagination.

Returns 200 OK with a paged envelope of SubjectView objects.

Errors

403: Not a member of the workspace

List a workspace's metered usage

GET/v1/workspaces/{wid}/usageList a workspace's metered usage

Keyset-paginated metered subjects of the workspace, each with the minutes and charge it accrued between from (inclusive) and to (exclusive). The window defaults to the current calendar month in UTC, up to now.

Path parameters

Name	Type	Required	Description
`wid`	string	yes	Workspace id

Query parameters

Name	Type	Required	Description
`from`	string	no	Start of the window, inclusive. Defaults to the start of the current UTC month ISO-8601 date-time.
`to`	string	no	End of the window, exclusive. Defaults to now ISO-8601 date-time.
`q`	string	no	Quick search by resource name, or an exact subject id
`id`	string[]	no	Subject ids to filter
`state`	string[]	no	States to filter Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`.
`resource_kind`	string[]	no	Kinds to filter Values: `SERVER`, `IP_ADDRESS`.
`package_code`	string[]	no	Package SKUs to filter
`charge_basis`	string[]	no	Charge bases to filter Values: `FIXED`, `METERED`.

Supports pagination.

Returns 200 OK with a paged envelope of SubjectUsageResponse objects.

Errors

400: The window ends before it starts
403: Not a member of the workspace

Gateway webhooks

Ingest a gateway webhook

POST/v1/webhooks/{gateway}Ingest a gateway webhook

We accept raw payment gateway events without bearer authentication. Gateway-specific verification uses the original payload and headers. This endpoint is for gateway delivery, not for confirming a payment from a customer script. Preserve the signed bytes and provider headers.

Path parameters

Name	Type	Required	Description
`gateway`	string	yes	`STRIPE`, `PAYPAL`, or `MANUAL`

Request body

The body is required. The specification represents it as a string with format: byte under application/json. The controller consumes raw bytes. Send the original gateway payload without wrapping or re-encoding it.

We record a first delivery and apply it asynchronously to the payment. Duplicate event references are ignored and move no money.

Returns 200 OK with WebhookResponse:

Field	Type	Required	Description
`event_id`	string	yes	Recorded event id
`event_ref`	string	yes	Gateway event reference
`gateway`	string	yes	Originating gateway Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`payment_id`	string or null	no	Payment this event reconciled, if any
`status`	string	yes	RECEIVED when the event is accepted for processing, IGNORED when it repeats one already accepted or carries nothing to act on Values: `RECEIVED`, `PROCESSED`, `IGNORED`, `FAILED`.
`type`	string	yes	Normalized event type

The initial outcome is RECEIVED or IGNORED. The response schema also permits PROCESSED and FAILED. Concurrent ingestion of the same event returns 409 Conflict. Retry that delivery.

Data objects

AccountView

A billing account, one per user, owning the wallet its subjects bill against.

Field	Type	Required	Description
`consolidated_billing`	boolean	yes	Whether the account may buy fixed packages as POSTPAID, billed on the monthly invoice
`created_at`	string	yes	Creation timestamp of the account ISO-8601 date-time.
`credit_limit`	integer	yes	How far the wallet may go negative before new authorizations stop, in micro-USD (1 USD = 1,000,000). Defaults to 0
`grace_period_seconds`	integer	yes	How long past an invoice due date the subjects stay up before suspension, in seconds. Defaults to 0
`id`	string	yes	Account id
`name`	string	yes	Account display name
`next_payment_at`	string or null	no	When the payment run next falls due. Null while none is scheduled ISO-8601 date-time.
`payment_day`	integer or null	no	The account's monthly date: the day of the monthly invoice and of MONTHLY_DATE renewals. In shorter months, the last day of the month applies. Null until the first purchase
`postpaid_partial`	boolean	yes	Whether a postpaid subject bills only the consumed part of its final cycle
`prepaid_credit`	boolean	yes	Whether cancelling a prepaid subject early refunds its unused portion as wallet credit
`state`	string	yes	Lifecycle state of the account Values: `ACTIVE`, `CLOSED`.
`user`	UserSimple	yes	User the account bills for

CancelQuoteResponse

The refund that a cancel of the subject gives at this time.

Field	Type	Required	Description
`period_end`	string or null	no	End of the subject's current cycle. Null for a subject billed without cycles ISO-8601 date-time.
`reason`	string	yes	The reason for the refund amount Values: `REFUNDED`, `FORFEIT`, `NOTHING_UNUSED`, `UNPAID`, `METERED`, `POSTPAID`.
`refund`	integer	yes	Wallet credit the cancel refunds, micro-USD. 0 unless reason is REFUNDED

CheckoutResponse

A checkout session to mount in the browser. The payment is pending until the customer completes it and the gateway confirms settlement, which for a bank transfer or direct debit can take days.

Field	Type	Required	Description
`client_secret`	string	yes	Client secret Stripe.js initializes the checkout with
`payment_id`	string or null	no	Pending payment this checkout collects. Null when the checkout only stores a method
`session_ref`	string	yes	Gateway session reference

CouponRedemptionView

One coupon a user redeemed and the credit it granted.

Field	Type	Required	Description
`amount`	integer	yes	Credit the coupon grants, micro-USD
`code`	string	yes	Code of the coupon redeemed
`coupon_id`	string	yes	Coupon redeemed
`credit_lot_id`	string	yes	Credit lot the redemption minted in the wallet
`id`	string	yes	Redemption id
`redeemed_at`	string	yes	When the coupon was redeemed ISO-8601 date-time.

CouponValidity

Whether a coupon code can be redeemed, and what redeeming it would grant.

Field	Type	Required	Description
`amount`	integer or null	no	Credit redeeming it grants, micro-USD. Null when no coupon carries that code
`expiry_days`	integer or null	no	Days after redemption the granted credit expires. Null when the credit never expires or when no coupon carries that code
`reason`	string or null	no	Why it cannot be redeemed. Null when it can Values: `NOT_FOUND`, `EXHAUSTED`, `ALREADY_REDEEMED`.
`valid`	boolean	yes	Whether the coupon can be redeemed

CreateOrderItemRequest

One line on an order: a package to purchase, or a change to an existing subject on an upgrade.

Field	Type	Required	Description
`package_code`	string	yes	Package SKU code: the package to buy, or on an upgrade the package the subject moves to, which may be its current one to choose new values for its open fields.
`properties`	KindProperties or null	no	Purchase only: provisioning inputs for the new resource. A SERVER purchase must name the template or backup to install. The kind must match the package's kind. These values do not change the price and are never returned. An upgrade rejects this field.
`prorate`	boolean or null	no	Upgrade only: split the in-progress cycle at now and prorate the change. Defaults to true. Ignored on a purchase.
`resource_name`	string or null	no	Display name for the resource. Defaults to the package name. A server's name is also its hostname: letters, digits and hyphens in dot-separated labels, at most 63 characters.
`spec`	KindSpec or null	no	Values for the fields the package leaves open, typed by the package's kind. On an upgrade, an open field left out keeps the subject's current value.
`target_subject_id`	string or null	no	On an upgrade, the id of the subject to change. Required for an upgrade item, and the subject must belong to the order's workspace.

CreateOrderResponse

The result of placing an order.

Field	Type	Required	Description
`authorized`	boolean	yes	Whether the order is currently `GREEN`. This does not confirm that provisioning has finished.
`collection`	string	yes	Use `NONE` when nothing is owed, wait for settlement with `IN_FLIGHT`, open a checkout with `REQUIRED`, ask the workspace owner to approve with `APPROVAL_REQUIRED`, or have the owner pay with `OWNER_REQUIRED`. Values: `NONE`, `IN_FLIGHT`, `REQUIRED`, `APPROVAL_REQUIRED`, `OWNER_REQUIRED`.
`invoice_id`	string or null	no	Invoice raised to collect the order, if any
`order`	OrderView	yes	The order as it stands after placement

GatewayClientConfig

Configuration to initialise the client library of one gateway

One of StripeClientConfig.

InvoiceRenderResponse

A rendered invoice: its own fields flattened inline, plus the line items composing it.

Field	Type	Required	Description
`account_id`	string	yes	Account the invoice is billed to
`amount_due`	integer	yes	Amount still payable on this invoice, micro-USD
`amount_paid`	integer	yes	Amount already applied to this invoice, micro-USD
`created_at`	string	yes	Creation time of the invoice ISO-8601 date-time.
`currency`	string	yes	ISO 4217 currency code of the invoice
`due_at`	string or null	no	Payment due date, stamped when the invoice is issued ISO-8601 date-time.
`id`	string	yes	Invoice id
`issued_at`	string or null	no	Issue time, null while the invoice is DRAFT ISO-8601 date-time.
`kind`	string	yes	CONSOLIDATED, TOPUP or ORDER Values: `CONSOLIDATED`, `TOPUP`, `ORDER`.
`line_items`	InvoiceLineItemView[]	yes	Line items composing the invoice subtotal
`number`	string or null	no	Human-readable invoice number, allocated when the invoice is issued and null while DRAFT
`paid_at`	string or null	no	Settlement time, null until the invoice is fully paid ISO-8601 date-time.
`pending_payment_count`	integer	yes	How many payments against this invoice are still awaiting confirmation
`period_end`	string or null	no	End of the billed period, if the invoice covers one ISO-8601 date-time.
`period_start`	string or null	no	Start of the billed period, if the invoice covers one ISO-8601 date-time.
`status`	string	yes	DRAFT, OPEN, PAID, VOID or UNCOLLECTIBLE Values: `DRAFT`, `OPEN`, `PAID`, `VOID`, `UNCOLLECTIBLE`.
`subject_id`	string or null	no	Billing subject this invoice covers, null for consolidated and top-up invoices
`subtotal`	integer	yes	Sum of the line items before tax, micro-USD
`tax_total`	integer	yes	Tax charged on top of the subtotal, micro-USD
`total`	integer	yes	Total invoiced, subtotal plus tax, micro-USD
`user`	UserSimple	yes	User the account bills for

InvoiceLineItemView

One priced line composing an invoice's subtotal.

Field	Type	Required	Description
`amount`	integer	yes	Total charged on this line, micro-USD
`created_at`	string	yes	Creation time of the line item ISO-8601 date-time.
`description`	string	yes	Human-readable description of the charge
`id`	string	yes	Line item id
`invoice_id`	string	yes	Invoice this line belongs to
`kind`	string	yes	FIXED_CYCLE, RENEWAL, METERED_USAGE, TOPUP, PRORATION_REFUND, CREDIT, ADJUSTMENT or TAX Values: `FIXED_CYCLE`, `RENEWAL`, `METERED_USAGE`, `TOPUP`, `PRORATION_REFUND`, `CREDIT`, `ADJUSTMENT`, `TAX`.
`metadata`	object or null	no	Free-form details attached to the line
`period_end`	string or null	no	End of the period this line covers, if any ISO-8601 date-time.
`period_start`	string or null	no	Start of the period this line covers, if any ISO-8601 date-time.
`quantity`	integer	yes	Number of units billed on this line
`subject_id`	string or null	no	Billing subject this line is charged for, if any
`unit_amount`	integer	yes	Price of a single unit, micro-USD

InvoiceView

A collection request against an account, with its totals, status and lifecycle timestamps.

Field	Type	Required	Description
`account_id`	string	yes	Account the invoice is billed to
`amount_due`	integer	yes	Amount still payable on this invoice, micro-USD
`amount_paid`	integer	yes	Amount already applied to this invoice, micro-USD
`created_at`	string	yes	Creation time of the invoice ISO-8601 date-time.
`currency`	string	yes	ISO 4217 currency code of the invoice
`due_at`	string or null	no	Payment due date, stamped when the invoice is issued ISO-8601 date-time.
`id`	string	yes	Invoice id
`issued_at`	string or null	no	Issue time, null while the invoice is DRAFT ISO-8601 date-time.
`kind`	string	yes	CONSOLIDATED, TOPUP or ORDER Values: `CONSOLIDATED`, `TOPUP`, `ORDER`.
`number`	string or null	no	Human-readable invoice number, allocated when the invoice is issued and null while DRAFT
`paid_at`	string or null	no	Settlement time, null until the invoice is fully paid ISO-8601 date-time.
`pending_payment_count`	integer	yes	How many payments against this invoice are still awaiting confirmation
`period_end`	string or null	no	End of the billed period, if the invoice covers one ISO-8601 date-time.
`period_start`	string or null	no	Start of the billed period, if the invoice covers one ISO-8601 date-time.
`status`	string	yes	DRAFT, OPEN, PAID, VOID or UNCOLLECTIBLE Values: `DRAFT`, `OPEN`, `PAID`, `VOID`, `UNCOLLECTIBLE`.
`subject_id`	string or null	no	Billing subject this invoice covers, null for consolidated and top-up invoices
`subtotal`	integer	yes	Sum of the line items before tax, micro-USD
`tax_total`	integer	yes	Tax charged on top of the subtotal, micro-USD
`total`	integer	yes	Total invoiced, subtotal plus tax, micro-USD
`user`	UserSimple	yes	User the account bills for

KindProperties

Provisioning inputs for a purchase, typed by kind

One of ServerProperties or IpAddressProperties.

Choose the object using its kind field.

IpAddressProperties

Provisioning inputs for an IP_ADDRESS. it takes none.

Field	Type	Required	Description
`kind`	string	yes	The kind these properties are for Values: `IP_ADDRESS`.

KindSpec

Values for the fields a package leaves open, typed by kind

One of ServerSpec or IpAddressSpec.

Choose the object using its kind field.

IpAddressSpec

Values for an IP_ADDRESS package's open fields.

Field	Type	Required	Description
`ddos`	boolean or null	no	Whether the address is DDoS protected
`family`	string or null	no	Address family Values: `IPv4`, `IPv6`.
`kind`	string	yes	The kind this spec is for Values: `IP_ADDRESS`.
`region`	string or null	no	Where the address is routed Values: `NA_01`.

LedgerEntryView

One line of a wallet's append-only journal, recording a single movement of credit.

Field	Type	Required	Description
`actor`	UserSimple or null	no	User who initiated the movement, if any
`amount`	integer	yes	Signed movement amount, micro-USD. positive credits, negative draws
`balance_after`	integer	yes	Wallet balance after this entry, micro-USD
`created_at`	string	yes	When the entry was written ISO-8601 date-time.
`group_ref`	string or null	no	Ties together the entries a single draw produces across credit lots
`id`	string	yes	Ledger entry id
`invoice_id`	string or null	no	Invoice this entry relates to, if any
`lot_id`	string or null	no	Credit lot this entry credits or draws. Null on an overdraft entry
`reference`	string or null	no	Free-form reference describing the movement
`subject_id`	string or null	no	Billing subject this entry is attributed to, if any
`type`	string	yes	Kind of movement this entry records Values: `TOPUP`, `USAGE_CHARGE`, `FIXED_CHARGE`, `INVOICE_SETTLEMENT`, `REFUND`, `ADJUSTMENT`, `COUPON`, `EXPIRY`, `CANCEL_REFUND`, `REPRICE_REFUND`.
`wallet_id`	string	yes	Wallet this entry belongs to

OrderDetailResponse

An order with its items and their part lines.

Field	Type	Required	Description
`items`	Item[]	yes	The order's items, each with its part lines
`order`	OrderView	yes	The order

Item

An order item with its part lines.

Field	Type	Required	Description
`item`	OrderItemView	yes	The item
`parts`	OrderItemPartView[]	yes	The item's part lines

OrderItemPartView

One field of an order item, with its priced contribution.

Field	Type	Required	Description
`amount`	integer	yes	This part's contribution to the item charge, micro-USD
`id`	string	yes	Order item part id
`order_item_id`	string	yes	Order item this part belongs to
`part_code`	string	yes	Field code
`quantity`	integer or null	no	Value of a numeric field
`rate_card_id`	string or null	no	Rate card that priced this part, if any
`unit_price`	integer	yes	Monthly rate snapshot, micro-USD
`value`	string or null	no	Value of an enum or boolean field

OrderItemView

One package on an order, with its snapshotted price and charge terms.

Field	Type	Required	Description
`amount`	integer	yes	This item's contribution to the order total, micro-USD
`base_price`	integer	yes	Flat base price snapshot, micro-USD
`charge_basis`	string	yes	FIXED or METERED Values: `FIXED`, `METERED`.
`cycle_count`	integer or null	no	Cycle length in units
`cycle_unit`	string or null	no	Cycle unit, e.g. MONTH
`id`	string	yes	Order item id
`kind`	string	yes	PURCHASE or UPGRADE Values: `PURCHASE`, `UPGRADE`, `ADJUST`.
`order_id`	string	yes	Order this item belongs to
`package_code`	string	yes	Package SKU code purchased
`payment_mode`	string	yes	PREPAID or POSTPAID Values: `PREPAID`, `POSTPAID`.
`resource_kind`	string	yes	Kind of resource this item bills for Values: `SERVER`, `IP_ADDRESS`.
`resource_name`	string	yes	Display name for the resource
`subject_id`	string or null	no	Subject created for this item on green, null until then
`target_subject_id`	string or null	no	Subject an upgrade targets, null for a purchase

OrderView

A purchase or upgrade transaction, with its totals, status and the invoice it collects on.

Field	Type	Required	Description
`account_id`	string	yes	Account the order is billed to
`actor`	UserSimple	yes	User who placed the order
`created_at`	string	yes	Creation time of the order ISO-8601 date-time.
`greened_at`	string or null	no	Time the order greened into subjects, null until then ISO-8601 date-time.
`id`	string	yes	Order id
`invoice_id`	string or null	no	Invoice raised to collect the order, null until one is raised
`kind`	string	yes	PURCHASE or UPGRADE Values: `PURCHASE`, `UPGRADE`, `ADJUST`.
`status`	string	yes	DRAFT, AWAITING_APPROVAL, AWAITING_PAYMENT, GREEN, FULFILLED, FAILED or CANCELLED. FAILED means the invoice was not paid, or the subject changed before a paid plan change applied and the payment was returned as account credit. Values: `DRAFT`, `AWAITING_APPROVAL`, `AWAITING_PAYMENT`, `GREEN`, `FULFILLED`, `FAILED`, `CANCELLED`.
`subtotal`	integer	yes	Sum of the item amounts before tax, micro-USD
`total`	integer	yes	Total to collect for the order, micro-USD
`user`	UserSimple	yes	Workspace owner the order bills
`workspace`	WorkspaceSimple or null	no	Workspace the order was placed in

PackageDetailResponse

A package with its offers, its rate card and its cheapest price.

Field	Type	Required	Description
`base_price`	integer	yes	Price per cycle covering every pinned field, micro-USD
`charge_basis`	string	yes	FIXED or METERED Values: `FIXED`, `METERED`.
`code`	string	yes	Unique package code
`created_at`	string	yes	Creation time ISO-8601 date-time.
`cycle_count`	integer or null	no	Cycle length in units
`cycle_unit`	string or null	no	Calendar cycle unit
`from_price`	integer or null	no	Cheapest price the package sells at, micro-USD: the base price plus every field the buyer chooses at its cheapest value. Per cycle for FIXED charge, per active hour for METERED. Equal to base_price when the buyer chooses nothing priced. Null when the package cannot be priced
`id`	string	yes	Package id
`name`	string	yes	Display name
`rate_card`	RateCardDetailResponse or null	no	Rate card for the fields the buyer selects. Null when the base price is the full price
`rate_card_id`	string or null	no	Rate card pricing the fields the buyer chooses
`resource_kind`	string	yes	Kind sold, which fixes the shape of the spec Values: `SERVER`, `IP_ADDRESS`.
`spec`	PackageSpecPartView[]	yes	One offer per field
`state`	string	yes	ACTIVE (sold) or RETIRED (not sold). A retired package stays readable by code Values: `ACTIVE`, `RETIRED`.

PackageSpecPartView

A package's offer for one field: a pinned value, or a choice left to the buyer.

Field	Type	Required	Description
`id`	string	yes	Spec part id
`max_qty`	integer or null	no	Largest value the buyer may choose for an open numeric field
`min_qty`	integer or null	no	Smallest value the buyer may choose for an open numeric field
`mode`	string	yes	PINNED (the package sets the value) or OPEN (the buyer chooses it) Values: `PINNED`, `OPEN`.
`package_id`	string	yes	Package this spec line belongs to
`part_code`	string	yes	Field code
`quantity`	integer or null	no	Pinned value of a numeric field
`value`	string or null	no	Pinned value of an enum or boolean field

PackageTransitionResponse

A move a subject on the source package may make, with the package it goes to.

Field	Type	Required	Description
`created_at`	string	yes	Creation time ISO-8601 date-time.
`direction`	string	yes	UPGRADE or DOWNGRADE Values: `UPGRADE`, `DOWNGRADE`.
`id`	string	yes	Transition id
`target`	PackageDetailResponse	yes	The package the move goes to, in the same shape as a package list item

PaymentMethodView

A payment method stored at a gateway so an account can be charged without the customer present.

Field	Type	Required	Description
`account_id`	string	yes	Account this method belongs to
`brand`	string or null	no	Card brand
`created_at`	string	yes	When the method was stored ISO-8601 date-time.
`exp_month`	integer or null	no	Card expiry month
`exp_year`	integer or null	no	Card expiry year
`gateway`	string	yes	Gateway holding this method Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`gateway_customer_ref`	string	yes	Gateway's own reference for the customer holding this method
`gateway_method_ref`	string	yes	Gateway's own reference for the stored method
`id`	string	yes	Payment method id
`is_default`	boolean	yes	Whether this is the account's default method for automatic charges
`last4`	string or null	no	Last four digits of the card
`user`	UserSimple	yes	User the account bills for

PaymentView

A real-money movement collected from or returned to an account through a payment gateway.

Field	Type	Required	Description
`account_id`	string	yes	Account this payment belongs to
`amount`	integer	yes	Payment amount, micro-USD
`captured_at`	string or null	no	When the gateway settled the payment. Null while it is pending ISO-8601 date-time.
`created_at`	string	yes	When the payment was created ISO-8601 date-time.
`credit_lot_id`	string or null	no	Wallet credit lot a succeeded inbound payment mints. Null otherwise
`currency`	string	yes	ISO currency code of the amount
`direction`	string	yes	INBOUND for money collected, REFUND for money returned Values: `INBOUND`, `REFUND`.
`failure_reason`	string or null	no	Why the gateway declined a failed payment. Null otherwise
`gateway`	string	yes	Gateway processing this payment Values: `STRIPE`, `PAYPAL`, `MANUAL`.
`gateway_ref`	string or null	no	Gateway's own reference for this payment
`id`	string	yes	Payment id
`invoice_id`	string or null	no	Invoice this payment applies to, if any
`payment_method_id`	string or null	no	Stored payment method charged for this payment, if any
`refund_of`	string or null	no	For a refund, ID of the original payment. Null otherwise
`refunded_amount`	integer	yes	Amount refunded from this payment, micro-USD. 0 if not refunded or if this payment is a refund
`status`	string	yes	PENDING until the gateway settles the payment, then SUCCEEDED, FAILED, or REFUNDED Values: `PENDING`, `SUCCEEDED`, `FAILED`, `REFUNDED`.
`user`	UserSimple	yes	User the account bills for

RateCardDetailResponse

A rate card with its prices.

Field	Type	Required	Description
`code`	string	yes	Unique rate card code
`created_at`	string	yes	Creation time ISO-8601 date-time.
`id`	string	yes	Rate card id
`name`	string	yes	Display name
`parts`	RateCardPartView[]	yes	Prices
`state`	string	yes	ACTIVE or RETIRED Values: `ACTIVE`, `RETIRED`.

RateCardPartView

One price on a rate card, micro-USD per month.

Field	Type	Required	Description
`id`	string	yes	Rate card part id
`part_code`	string	yes	Field code
`per_units`	integer	yes	How many units of a numeric field unit_price covers
`rate_card_id`	string	yes	Rate card this price belongs to
`unit_price`	integer	yes	Price per month, micro-USD: per per_units units, or flat for a value
`value`	string or null	no	The enum or boolean value this flat price is for. Null when the line prices a numeric field

RedeemCouponResponse

The result of a coupon redemption: the wallet after the grant and the COUPON ledger entry it wrote.

Field	Type	Required	Description
`entry`	LedgerEntryView	yes	The COUPON ledger entry recording the granted credit
`wallet`	WalletView	yes	The wallet as it stands after the credit lands

RenewalDayQuoteResponse

What moving a subject's renewal day costs at this time.

Field	Type	Required	Description
`anchor_day`	integer	yes	The day of the month the subject renews on after the move
`charge`	integer	yes	The charge for the added days, micro-USD
`new_period_end`	string	yes	When the subject renews after the move ISO-8601 date-time.
`period_end`	string	yes	When the subject renews before the move ISO-8601 date-time.

RenewalDayResponse

The result of moving a subject's renewal day.

Field	Type	Required	Description
`applied`	boolean	yes	Whether the renewal moved. False while the invoice for the added days is unpaid.
`collection`	string	yes	NONE if nothing is owed, IN_FLIGHT while a stored method is charging, REQUIRED to go to a checkout Values: `NONE`, `IN_FLIGHT`, `REQUIRED`, `APPROVAL_REQUIRED`, `OWNER_REQUIRED`.
`invoice_id`	string or null	no	The invoice for the added days, when they could not be paid from the wallet
`subject`	SubjectView	yes	The subject after the move

ServerProperties

Provisioning inputs for a SERVER.

Field	Type	Required	Description
`image`	string	yes	Template or backup installed on the disk
`kind`	string	yes	The kind these properties are for Values: `SERVER`.

ServerSpec

Values for a SERVER package's open fields.

Field	Type	Required	Description
`backup`	string or null	no	Backup schedule Values: `WEEKLY`, `DAILY`.
`cpu`	integer or null	no	Virtual CPU cores Minimum: `1`. Maximum: `128`.
`disk`	integer or null	no	Disk size in GiB Minimum: `10`. Maximum: `4000`. Multiple of: `10`.
`download`	integer or null	no	Download bandwidth in Mbps Minimum: `100`. Maximum: `10000`. Multiple of: `100`.
`io_read`	integer or null	no	Disk read limit in MiB/s Minimum: `1`. Maximum: `95000`.
`io_read_iops`	integer or null	no	Disk read limit in IOPS Minimum: `1`. Maximum: `10000000`.
`io_write`	integer or null	no	Disk write limit in MiB/s Minimum: `1`. Maximum: `95000`.
`io_write_iops`	integer or null	no	Disk write limit in IOPS Minimum: `1`. Maximum: `10000000`.
`ipv4`	integer or null	no	IPv4 addresses included Minimum: `0`. Maximum: `16`.
`ipv6`	integer or null	no	IPv6 addresses included Minimum: `0`. Maximum: `16`.
`kind`	string	yes	The kind this spec is for Values: `SERVER`.
`ram`	integer or null	no	Memory in MiB Minimum: `512`. Maximum: `524288`. Multiple of: `512`.
`region`	string or null	no	Where the server runs Values: `NA_01`.
`service_group`	string or null	no	Hardware line the server runs on Values: `LIGHTNING`, `RYZEN`, `DEDICATED`.
`storage_backend`	string or null	no	Storage the disk lives on Values: `LOCAL`, `CEPH`.
`upload`	integer or null	no	Upload bandwidth in Mbps Minimum: `100`. Maximum: `10000`. Multiple of: `100`.

StripeClientConfig

Configuration for Stripe.js and the checkout Payment Element

Field	Type	Required	Description
`publishable_key`	string	yes	Publishable API key for Stripe.js

SubjectDetailResponse

A subject with its spec and the priced fields behind its price.

Field	Type	Required	Description
`account_id`	string	yes	Account billed for this subject
`anchor_day`	integer or null	no	FIXED only: day of the month the cycle renews on, or the last day of a shorter month Minimum: `1`. Maximum: `31`.
`base_price`	integer	yes	Base price per cycle of the package, micro-USD
`charge_basis`	string	yes	FIXED (exact price per calendar cycle) or METERED (rate times active time) Values: `FIXED`, `METERED`.
`created_at`	string	yes	Creation time of the subject ISO-8601 date-time.
`current_period_end`	string or null	no	End of the current billing cycle ISO-8601 date-time.
`current_period_start`	string or null	no	Start of the current billing cycle ISO-8601 date-time.
`cycle_count`	integer or null	no	FIXED only: number of cycle units per billing period
`cycle_price`	integer or null	no	FIXED only: amount charged per cycle, micro-USD
`cycle_unit`	string or null	no	FIXED only: calendar cycle unit, MONTH or YEAR
`external_ref`	string or null	no	External collector reference, null when billing owns the meter
`id`	string	yes	Billing subject id
`last_tick_at`	string or null	no	Time of the most recent metered accrual ISO-8601 date-time.
`package_code`	string or null	no	SKU of the package the subject is on, null when it was not bought from the catalog
`paid_through_at`	string or null	no	Fixed-prepaid subjects: the time coverage is paid up to ISO-8601 date-time.
`parts`	SubjectPartView[]	yes	One line per field, with what it contributes to the price
`payment_mode`	string	yes	PREPAID or POSTPAID Values: `PREPAID`, `POSTPAID`.
`rate`	integer or null	no	METERED only: rate per active hour, micro-USD
`resource_id`	string or null	no	Upstream resource id, null for a subject bought through an order
`resource_kind`	string	yes	Kind of resource being billed Values: `SERVER`, `IP_ADDRESS`.
`resource_name`	string	yes	Name of the billed resource, retained even once the resource is gone
`spec`	object of object	yes	Every field the subject carries, keyed by field code: numbers, enum names and booleans
`state`	string	yes	ACTIVE, SUSPENDED or TERMINATED Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`.
`suspend_reason`	string or null	no	BILLING or OPERATIONAL while the subject is suspended Values: `BILLING`, `OPERATIONAL`.
`suspended_at`	string or null	no	Suspension time, null while the subject is not suspended ISO-8601 date-time.
`terminated_at`	string or null	no	Termination time, null until the subject is terminated ISO-8601 date-time.
`user`	UserSimple	yes	User the account bills for
`workspace`	WorkspaceSimple or null	no	Workspace the subject belongs to

SubjectPartView

One field of a subject, with its priced contribution.

Field	Type	Required	Description
`amount`	integer	yes	This part's contribution to the charge, micro-USD. 0 when bundled
`id`	string	yes	Subject part id
`part_code`	string	yes	Field code
`quantity`	integer or null	no	Value of a numeric field
`rate_card_id`	string or null	no	Rate card that priced this part, for audit
`subject_id`	string	yes	Subject this part belongs to
`unit_price`	integer	yes	Monthly rate snapshot, micro-USD. 0 when bundled into the subject base price
`value`	string or null	no	Value of an enum or boolean field

SubjectTransitionResponse

A move the subject's package offers, priced for this subject.

Field	Type	Required	Description
`created_at`	string	yes	Creation time ISO-8601 date-time.
`direction`	string	yes	UPGRADE or DOWNGRADE Values: `UPGRADE`, `DOWNGRADE`.
`eligible`	boolean	yes	Whether an upgrade order for this move, with no field changes, would be accepted now
`id`	string	yes	Transition id
`new_price`	integer or null	no	Price after the move with the subject's current values kept in the target's open fields, micro-USD: per cycle for FIXED, per active hour for METERED. Null when not eligible
`prorated_delta`	integer or null	no	Amount that a move now settles for the rest of the paid cycle, micro-USD: positive is charged, negative is refunded to the wallet. 0 unless the subject is FIXED PREPAID. Null when not eligible
`reason`	string or null	no	Why the move is refused, the same message the upgrade order returns. Null when eligible
`target`	PackageDetailResponse	yes	The package the move goes to, in the same shape as a package list item

SubjectUsageResponse

A metered subject with the usage it accrued over the requested window.

Field	Type	Required	Description
`account_id`	string	yes	Account billed for this subject
`anchor_day`	integer or null	no	FIXED only: day of the month the cycle renews on, or the last day of a shorter month Minimum: `1`. Maximum: `31`.
`base_price`	integer	yes	Base price per cycle of the package, micro-USD
`charge_basis`	string	yes	FIXED (exact price per calendar cycle) or METERED (rate times active time) Values: `FIXED`, `METERED`.
`created_at`	string	yes	Creation time of the subject ISO-8601 date-time.
`current_period_end`	string or null	no	End of the current billing cycle ISO-8601 date-time.
`current_period_start`	string or null	no	Start of the current billing cycle ISO-8601 date-time.
`cycle_count`	integer or null	no	FIXED only: number of cycle units per billing period
`cycle_price`	integer or null	no	FIXED only: amount charged per cycle, micro-USD
`cycle_unit`	string or null	no	FIXED only: calendar cycle unit, MONTH or YEAR
`external_ref`	string or null	no	External collector reference, null when billing owns the meter
`id`	string	yes	Billing subject id
`last_tick_at`	string or null	no	Time of the most recent metered accrual ISO-8601 date-time.
`package_code`	string or null	no	SKU of the package the subject is on, null when it was not bought from the catalog
`paid_through_at`	string or null	no	Fixed-prepaid subjects: the time coverage is paid up to ISO-8601 date-time.
`payment_mode`	string	yes	PREPAID or POSTPAID Values: `PREPAID`, `POSTPAID`.
`rate`	integer or null	no	METERED only: rate per active hour, micro-USD
`resource_id`	string or null	no	Upstream resource id, null for a subject bought through an order
`resource_kind`	string	yes	Kind of resource being billed Values: `SERVER`, `IP_ADDRESS`.
`resource_name`	string	yes	Name of the billed resource, retained even once the resource is gone
`state`	string	yes	ACTIVE, SUSPENDED or TERMINATED Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`.
`suspend_reason`	string or null	no	BILLING or OPERATIONAL while the subject is suspended Values: `BILLING`, `OPERATIONAL`.
`suspended_at`	string or null	no	Suspension time, null while the subject is not suspended ISO-8601 date-time.
`terminated_at`	string or null	no	Termination time, null until the subject is terminated ISO-8601 date-time.
`usage_amount`	integer	yes	Charge accrued in the window, micro-USD
`usage_from`	string	yes	Start of the window, inclusive ISO-8601 date-time.
`usage_minutes`	integer	yes	Metered minutes accrued in the window
`usage_to`	string	yes	End of the window, exclusive ISO-8601 date-time.
`user`	UserSimple	yes	User the account bills for
`workspace`	WorkspaceSimple or null	no	Workspace the subject belongs to

SubjectView

A billable resource together with its billing terms and current state.

Field	Type	Required	Description
`account_id`	string	yes	Account billed for this subject
`anchor_day`	integer or null	no	FIXED only: day of the month the cycle renews on, or the last day of a shorter month Minimum: `1`. Maximum: `31`.
`base_price`	integer	yes	Base price per cycle of the package, micro-USD
`charge_basis`	string	yes	FIXED (exact price per calendar cycle) or METERED (rate times active time) Values: `FIXED`, `METERED`.
`created_at`	string	yes	Creation time of the subject ISO-8601 date-time.
`current_period_end`	string or null	no	End of the current billing cycle ISO-8601 date-time.
`current_period_start`	string or null	no	Start of the current billing cycle ISO-8601 date-time.
`cycle_count`	integer or null	no	FIXED only: number of cycle units per billing period
`cycle_price`	integer or null	no	FIXED only: amount charged per cycle, micro-USD
`cycle_unit`	string or null	no	FIXED only: calendar cycle unit, MONTH or YEAR
`external_ref`	string or null	no	External collector reference, null when billing owns the meter
`id`	string	yes	Billing subject id
`last_tick_at`	string or null	no	Time of the most recent metered accrual ISO-8601 date-time.
`package_code`	string or null	no	SKU of the package the subject is on, null when it was not bought from the catalog
`paid_through_at`	string or null	no	Fixed-prepaid subjects: the time coverage is paid up to ISO-8601 date-time.
`payment_mode`	string	yes	PREPAID or POSTPAID Values: `PREPAID`, `POSTPAID`.
`rate`	integer or null	no	METERED only: rate per active hour, micro-USD
`resource_id`	string or null	no	Upstream resource id, null for a subject bought through an order
`resource_kind`	string	yes	Kind of resource being billed Values: `SERVER`, `IP_ADDRESS`.
`resource_name`	string	yes	Name of the billed resource, retained even once the resource is gone
`state`	string	yes	ACTIVE, SUSPENDED or TERMINATED Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`.
`suspend_reason`	string or null	no	BILLING or OPERATIONAL while the subject is suspended Values: `BILLING`, `OPERATIONAL`.
`suspended_at`	string or null	no	Suspension time, null while the subject is not suspended ISO-8601 date-time.
`terminated_at`	string or null	no	Termination time, null until the subject is terminated ISO-8601 date-time.
`user`	UserSimple	yes	User the account bills for
`workspace`	WorkspaceSimple or null	no	Workspace the subject belongs to

UsageRecordView

Metered usage for a billing subject over a single period, and the charge it produced.

Field	Type	Required	Description
`account_id`	string	yes	Account billed for the usage
`amount`	integer	yes	Charge for the metered minutes, micro-USD
`created_at`	string	yes	Creation time of the usage record ISO-8601 date-time.
`id`	string	yes	Usage record id
`invoice_id`	string or null	no	Invoice this usage is rolled up into, null until it is invoiced
`ledger_entry_id`	string or null	no	Ledger entry this usage is settled under, null until it is settled
`minutes`	integer	yes	Metered minutes in the period
`period_end`	string	yes	End of the metered period ISO-8601 date-time.
`period_start`	string	yes	Start of the metered period ISO-8601 date-time.
`rate`	integer	yes	Rate applied to the period, micro-USD per active hour
`subject_id`	string	yes	Billing subject the usage is metered for

UserSimple

User reference

Field	Type	Required	Description
`id`	string	yes	User ID
`name`	string	yes	User's name

WalletView

An account's prepaid balance, credited by top-ups and drawn down by charges.

Field	Type	Required	Description
`account_id`	string	yes	Account this wallet belongs to
`balance`	integer	yes	Current balance, micro-USD. negative when the account is overdrawn
`currency`	string	yes	ISO currency code of the balance
`id`	string	yes	Wallet id
`unbilled_usage`	integer	yes	Metered usage already drawn from the balance but not yet posted as a USAGE_CHARGE movement, micro-USD. The balance is authoritative
`updated_at`	string	yes	When the balance last changed ISO-8601 date-time.
`user`	UserSimple	yes	User the account bills for

WorkspaceSimple

Field	Type	Required	Description
`id`	string	yes
`name`	string	yes

Billing and usage ​

Catalog ​

List packages ​

Get a package ​

List a package's moves ​

Get a rate card ​

Orders ​

Get an order ​

Approve an order ​

Cancel an order ​

List a workspace's orders ​

Place an order ​

Accounts and wallets ​

Get a user's billing account ​

Move the account's monthly date ​

Get a user's wallet balance ​

List a user's wallet movements ​

Coupons ​

Redeem a coupon ​

List a user's coupon redemptions ​

Check whether a coupon can be redeemed ​

Invoices ​

Get a rendered invoice ​

List a user's invoices ​

Payments ​

Get the client payment configuration ​

Get a payment ​

List a user's payments ​

Open a checkout ​

Top up a wallet from the default payment method ​

Payment methods ​

Get a payment method ​

Delete a payment method ​

Set a method as default ​

List a user's payment methods ​

Confirm a stored method ​

Open a checkout to store a method ​

Billing subjects and usage ​

Get a subject ​

Cancel a purchase ​

Quote cancelling a subject ​

Move a subject's renewal day ​

Quote moving a subject's renewal day ​

List a subject's moves ​

List a subject's usage ​

List a workspace's subjects ​

List a workspace's metered usage ​

Gateway webhooks ​

Ingest a gateway webhook ​

Data objects ​

AccountView ​

CancelQuoteResponse ​

CheckoutResponse ​

CouponRedemptionView ​

CouponValidity ​

CreateOrderItemRequest ​

CreateOrderResponse ​

GatewayClientConfig ​

InvoiceRenderResponse ​

InvoiceLineItemView ​

InvoiceView ​

KindProperties ​

IpAddressProperties ​

KindSpec ​

IpAddressSpec ​

LedgerEntryView ​

OrderDetailResponse ​

Item ​

OrderItemPartView ​

OrderItemView ​

OrderView ​

PackageDetailResponse ​

PackageSpecPartView ​

PackageTransitionResponse ​

PaymentMethodView ​

PaymentView ​

RateCardDetailResponse ​

RateCardPartView ​

RedeemCouponResponse ​

RenewalDayQuoteResponse ​

Billing and usage

Catalog

List packages

Get a package

List a package's moves

Get a rate card

Orders

Get an order

Approve an order

Cancel an order

List a workspace's orders

Place an order

Accounts and wallets

Get a user's billing account

Move the account's monthly date

Get a user's wallet balance

List a user's wallet movements

Coupons

Redeem a coupon

List a user's coupon redemptions

Check whether a coupon can be redeemed

Invoices

Get a rendered invoice

List a user's invoices

Payments

Get the client payment configuration

Get a payment

List a user's payments

Open a checkout

Top up a wallet from the default payment method

Payment methods

Get a payment method

Delete a payment method

Set a method as default

List a user's payment methods

Confirm a stored method

Open a checkout to store a method

Billing subjects and usage

Get a subject

Cancel a purchase

Quote cancelling a subject

Move a subject's renewal day

Quote moving a subject's renewal day

List a subject's moves

List a subject's usage

List a workspace's subjects

List a workspace's metered usage

Gateway webhooks

Ingest a gateway webhook

Data objects

AccountView

CancelQuoteResponse

CheckoutResponse

CouponRedemptionView

CouponValidity

CreateOrderItemRequest

CreateOrderResponse

GatewayClientConfig

InvoiceRenderResponse

InvoiceLineItemView

InvoiceView

KindProperties

IpAddressProperties

KindSpec

IpAddressSpec

LedgerEntryView

OrderDetailResponse

Item

OrderItemPartView

OrderItemView

OrderView

PackageDetailResponse

PackageSpecPartView

PackageTransitionResponse

PaymentMethodView

PaymentView

RateCardDetailResponse

RateCardPartView

RedeemCouponResponse

RenewalDayQuoteResponse