AnkraDocs
Console

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#

GET/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

200 response fields
FieldTypeDescription
payments_configuredrequiredboolean
publishable_keyrequiredstring | nullStripe publishable key (pk_…), when configured.
standingrequiredAccountStandingWhether the account may create billable resources; a refused create answers 402 with the same reason.
requires_billing_approvalrequiredbooleanSaving a card does not authorise paid usage.
billing_arrangementrequiredstringcard: 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_resourcesrequiredbooleanFalse 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.
reasonrequiredstring | nullWhy 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_coverrequiredAccountCreditCover | nullWhat 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_centsrequiredintegerWhat 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_centsrequiredintegerOne 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_centsrequiredintegeravailable_cents minus committed_monthly_cents, never below zero: the monthly list price the account can still add without a payment method.
next_expiryrequiredstring (date-time) | nullThe soonest expiry of a live credit; null without one. A credit pays for nothing after it.
suspended_for_payment_atrequiredstring (date-time) | nullWhen an invoice overdue past the grace period suspended the account; null while it is in good standing.
suspended_by_staff_atrequiredstring (date-time) | nullWhen Ankra staff suspended the account; null while they have not. Paying an invoice does not lift it; contact support.
unpaid_usage_sincerequiredstring (date-time) | nullWhen 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_atrequiredstring (date-time) | nullWhen 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_urlrequiredstring (uri) | nullThe 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_trialrequiredDevClusterTrialOffer | nullWhether the account may start a free trial dev cluster while it cannot create billable resources; null when the deployment offers no trials.
is_availablerequiredboolean
reasonrequiredstring | nullOne of not_linked_to_platform, trial_running, trials_used, dev_clusters_not_offered
detailrequiredstring | nullWhy the trial is not on offer, in a sentence.
trials_used_in_windowrequiredinteger
running_trial_idrequiredstring | nullThe account's live trial dev cluster.
termsrequiredDevClusterTrialTerms
lifetime_hoursrequiredintegerHow long a trial runs before it is deleted with its server.
maximum_coresrequiredintegerThe largest plan's cores a trial may use.
maximum_memory_mebibytesrequiredintegerThe largest plan's memory a trial may use.
trials_per_windowrequiredintegerHow many trials an account may start in window_days.
window_daysrequiredinteger
  • 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/account/billing' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

The account's saved payment methods#

GET/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

Parameters
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of payment methods.application/json · PaymentMethodList

200 response fields
FieldTypeDescription
itemsrequiredarray of PaymentMethod
idrequiredstring
typerequiredstring
brandrequiredstringCard brand; empty for other types.
last4requiredstring
exp_monthrequiredinteger
exp_yearrequiredinteger
is_defaultrequiredboolean
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/account/billing/payment-methods' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Detach a saved payment method#

DELETE/v1/account/billing/payment-methods/{id}
Operation
remove_payment_method
Credentials
API token, Portal session
Requires
Permission billing.manage

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

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_credentials on 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

bash
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#

POST/v1/account/billing/payment-methods/{id}/default
Operation
set_default_payment_method
Credentials
API token, Portal session
Requires
Permission billing.manage

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

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_credentials on 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

bash
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#

POST/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

201 response fields
FieldTypeDescription
urlrequiredstring (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_credentials on 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

bash
curl -X POST 'https://cloud.ankra.app/v1/account/billing/setup-session' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"