API reference · Account and billing

Credits and coupons

2 operations of the Ankra Cloud API: Account credits, coupon redemption, and credit and coupon management for staff.

Redeem a coupon code for account credit#

POST/v1/account/coupons

Operation: redeem_coupon
Credentials: API token, Portal session
Requires: Permission billing.manage

Grants the coupon's credit, which expires the coupon's validity days from now. A code is redeemed at most once per account and never beyond its cap; the check and the redemption happen under a lock on the coupon, so concurrent redemptions cannot exceed it. Codes compare case-insensitively. The redemption, and a refused attempt, are written to the account's audit log (billing.coupon.redeem).

Request bodyapplication/json · RedeemCouponRequest

Request body fields
Field	Type	Description
`code`required	string

Responses

201The credit was granted.application/json · CouponRedemption

201 response fields
Field	Type	Description
`code`required	string
`description`required	string
`credit`required	Credit
`id`required	string
`source`required	string	One of `coupon`, `staff`
`source_id`required	string \| null	The coupon that granted it.
`label`required	string
`currency`required	string
`amount_cents`required	integer
`remaining_cents`required	integer
`granted_at`required	string (date-time)
`expires_at`required	string (date-time)
`status`required	string	`expired` credits keep `remaining_cents` for the record; they still pay for usage from before their expiry on an invoice not issued yet, never for later usage.One of `active`, `used`, `expired`, `voided`

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).
422The code cannot be applied; reason says why.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/account/coupons' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "WELCOME500"
}'

The account's credits and what they have left#

GET/v1/account/credits

Operation: list_account_credits
Credentials: API token, Portal session
Requires: Permission billing.read

Every credit the account was granted (coupon redemptions, staff grants), newest first, with its status at the time of the response. balance_cents sums what live credits have left. A credit pays for the usage incurred between granted_at and expires_at (metered hours, and days of network transfer, that overlap that window), on the invoice of the month the usage was in, whenever that invoice is issued; the soonest-expiring credit pays first. Usage outside every credit's window is charged.

Parameters

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 credits with the balance.application/json · CreditList

200 response fields
Field	Type	Description
`currency`required	string
`balance_cents`required	integer
`next_expiry`required	string (date-time) \| null
`items`required	array of Credit
`id`required	string
`source`required	string	One of `coupon`, `staff`
`source_id`required	string \| null	The coupon that granted it.
`label`required	string
`currency`required	string
`amount_cents`required	integer
`remaining_cents`required	integer
`granted_at`required	string (date-time)
`expires_at`required	string (date-time)
`status`required	string	`expired` credits keep `remaining_cents` for the record; they still pay for usage from before their expiry on an invoice not issued yet, never for later usage.One of `active`, `used`, `expired`, `voided`
`next_cursor`required	string \| null	Pass 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).
defaultAny other error, usually 500.

Example

bash

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