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
| 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. |
can_create_resourcesrequired | boolean | |
reasonrequired | string | null | Why the account may not create billable resources; null while it may. account_suspended covers both suspensions; the two timestamps say which hold.One of payment_method_required, owner_approval_required, account_suspended |
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. |
- 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). - 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#
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
| 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). - 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#
DELETE
/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.
- 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#
POST
/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.
- 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#
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
| 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). - 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"