API reference · Account and billing
Payments
5 operations of the Ankra Cloud API: Payment methods and the Stripe webhook.
Whether card payments through Stripe are available#
/v1/account/billing- Operation
get_payment_configuration- Credentials
- API token, Portal session
- Requires
- Permission
billing.read
When payments_configured is false the other /v1/account/billing/* routes answer 503 and invoices stay unbilled. standing says whether the account may create billable resources (the same reason a refused create answers 402 with).
Responses
200The payment configuration.application/json · PaymentConfiguration
| Field | Type | Description |
|---|---|---|
payments_configuredrequired | boolean | |
publishable_keyrequired | string | null | Stripe publishable key (pk_…), when configured. |
standingrequired | AccountStanding | Whether the account may create billable resources; a refused create answers 402 with the same reason. |
requires_billing_approvalrequired | boolean | Saving a card does not authorise paid usage. |
billing_arrangementrequired | string | card: Cloud charges the invoices through Stripe, and a default payment method is required to create billable resources whatever credit the account holds; credit is spent first. invoice: the Ankra platform invoices the organisation under its own agreement, so no card and no owner approval are needed and Cloud never charges the account's invoices. prepaid: the account is linked to an Ankra platform organisation and spends only its credit; a default payment method is required but never charged (payment_method_required while none is on file), no owner approval is needed, and with a card on file a create is refused with credit_required when the credit does not cover it: a top-up on the Ankra platform (top_up_url), not a card, lifts it.One of card, invoice, prepaid |
can_create_resourcesrequired | boolean | False while every billable create would be refused. An account billed by card without a default payment method may not create anything, whatever credit it holds. |
reasonrequired | string | null | Why the account may not create billable resources; null while it may. payment_method_required: no default payment method (add one). credit_required: a prepaid account with a card on file whose credit has nothing spendable left (top up on the Ankra platform, top_up_url). account_suspended covers both suspensions; the two timestamps say which hold. Clients should treat an unknown value as a refusal.One of payment_method_required, credit_required, owner_approval_required, account_suspended |
credit_coverrequired | AccountCreditCover | null | What the account's credit would pay for while it has no default payment method; such an account may not create until it adds one. Null once it has one, for an account the platform invoices, and while payments are not configured; always set for a prepaid account, whose credit caps what it may create. |
available_centsrequired | integer | What the account's live credits have left after the usage metered so far (the credit balance). It is the figure the unpaid usage notice reads too: once it reaches zero while a billable server runs, the account is told (unpaid_usage_since). |
committed_monthly_centsrequired | integer | One month, at monthly list prices, of every billable resource the account holds now, and of the nodes its Kubernetes node pools may still add (up to each pool's node count or autoscaling maximum). |
spendable_monthly_centsrequired | integer | available_cents minus committed_monthly_cents, never below zero: the monthly list price the account can still add without a payment method. |
next_expiryrequired | string (date-time) | null | The soonest expiry of a live credit; null without one. A credit pays for nothing after it. |
suspended_for_payment_atrequired | string (date-time) | null | When an invoice overdue past the grace period suspended the account; null while it is in good standing. |
suspended_by_staff_atrequired | string (date-time) | null | When Ankra staff suspended the account; null while they have not. Paying an invoice does not lift it; contact support. |
unpaid_usage_sincerequired | string (date-time) | null | When the account was first seen running billable servers that nothing pays for: it is billed by card, has no payment method on file and no credit left. Null while a payment method, a credit or an invoice arrangement pays. |
servers_stop_atrequired | string (date-time) | null | When the account's servers are powered off for unpaid usage (seven days after the account was told), or were. Powering off keeps disks, addresses and data; adding a payment method under Settings, Billing ends it. Null while something pays, and until the account was told. |
top_up_urlrequired | string (uri) | null | The Ankra platform billing page where a prepaid account's organisation tops up its credit; null for any other account, and when Cloud cannot name the page (no platform web origin configured). |
dev_cluster_trialrequired | DevClusterTrialOffer | null | Whether the account may start a free trial dev cluster while it cannot create billable resources; null when the deployment offers no trials. |
is_availablerequired | boolean | |
reasonrequired | string | null | One of not_linked_to_platform, trial_running, trials_used, dev_clusters_not_offered |
detailrequired | string | null | Why the trial is not on offer, in a sentence. |
trials_used_in_windowrequired | integer | |
running_trial_idrequired | string | null | The account's live trial dev cluster. |
termsrequired | DevClusterTrialTerms | |
lifetime_hoursrequired | integer | How long a trial runs before it is deleted with its server. |
maximum_coresrequired | integer | The largest plan's cores a trial may use. |
maximum_memory_mebibytesrequired | integer | The largest plan's memory a trial may use. |
trials_per_windowrequired | integer | How many trials an account may start in window_days. |
window_daysrequired | integer |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/account/billing' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"The account's saved payment methods#
/v1/account/billing/payment-methods- Operation
list_payment_methods- Credentials
- API token, Portal session
- Requires
- Permission
billing.read - Note
- Reveals a credential or a live view; read-only support sessions are refused.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of payment methods.application/json · PaymentMethodList
| Field | Type | Description |
|---|---|---|
itemsrequired | array of PaymentMethod | |
idrequired | string | |
typerequired | string | |
brandrequired | string | Card brand; empty for other types. |
last4required | string | |
exp_monthrequired | integer | |
exp_yearrequired | integer | |
is_defaultrequired | boolean | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503Payments are not configured on this control plane (
payments not configured). - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/account/billing/payment-methods' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Detach a saved payment method#
/v1/account/billing/payment-methods/{id}- Operation
remove_payment_method- Credentials
- API token, Portal session
- Requires
- Permission
billing.manage
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
204Removed.
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503Payments are not configured on this control plane (
payments not configured). - defaultAny other error, usually 500.
Example
curl -X DELETE 'https://cloud.ankra.app/v1/account/billing/payment-methods/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Charge invoices to this payment method#
/v1/account/billing/payment-methods/{id}/default- Operation
set_default_payment_method- Credentials
- API token, Portal session
- Requires
- Permission
billing.manage
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
204It is the default now.
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503Payments are not configured on this control plane (
payments not configured). - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/account/billing/payment-methods/<id>/default' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Start Stripe's hosted page for saving a payment method#
/v1/account/billing/setup-session- Operation
create_payment_setup_session- Credentials
- API token, Portal session
- Requires
- Permission
billing.manage
Creates the account's Stripe customer on first use and a Checkout session in setup mode (nothing is charged). Redirect the customer to url; Stripe sends them back to /settings/billing.
Responses
201The hosted page to redirect to.application/json · PaymentSetupSession
| Field | Type | Description |
|---|---|---|
urlrequired | string (uri) |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503Payments are not configured on this control plane (
payments not configured). - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/account/billing/setup-session' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"