API: Billing

Generated from the API's OpenAPI schema. Paths are relative to https://cloud.tebibhost.com. Authentication, errors, pagination and idempotency are on the API overview.

GET/api/v1/fx-rates

List Fx Rates (listFxRates)

IAM action: none (public, no sign-in)

Responses

• 200 OK (array of FxRateOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

GET/api/v1/orgs/{organization_id}/billing

Get Billing (getBilling)

IAM action: billing:GetBilling

Parameter	In	Type	Description
organization_id required	path	string

Responses

• 200 OK (BillingOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of BillingOut

Field	Type	Description
account_reference	string
available	string
available_micro	integer
contacts	array of string
credit_limit_micro	integer
currency	string
organization_id	string
payment_methods	array of PaymentMethodOut
promo	string
promo_micro	integer
run_rate_micro_per_hour	integer (nullable)
runway_hours	number (nullable)
state	string
state_since	string (date-time)
wallet	string
wallet_micro	integer

PATCH/api/v1/orgs/{organization_id}/billing

Update Billing (updateBilling)

IAM action: billing:UpdateBilling

Parameter	In	Type	Description
organization_id required	path	string

Request body (JSON, BillingPatch)

Field	Type	Description
contacts required	array of string

Responses

• 200 OK (BillingOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of BillingOut

Field	Type	Description
account_reference	string
available	string
available_micro	integer
contacts	array of string
credit_limit_micro	integer
currency	string
organization_id	string
payment_methods	array of PaymentMethodOut
promo	string
promo_micro	integer
run_rate_micro_per_hour	integer (nullable)
runway_hours	number (nullable)
state	string
state_since	string (date-time)
wallet	string
wallet_micro	integer

GET/api/v1/orgs/{organization_id}/billing/statements

List Statements (listStatements)

Monthly statements, newest first.

IAM action: billing:ListStatements

Parameter	In	Type	Description
organization_id required	path	string
limit	query	integer (nullable)
cursor	query	string (nullable)

Responses

• 200 OK (Page_StatementSummaryOut_)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of Page_StatementSummaryOut_

Field	Type	Description
items	array of StatementSummaryOut
next_cursor	string (nullable)

GET/api/v1/orgs/{organization_id}/billing/statements/{statement_id}

Get Statement (getStatement)

IAM action: billing:GetStatement

Parameter	In	Type	Description
organization_id required	path	string
statement_id required	path	string

Responses

• 200 OK (StatementOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of StatementOut

Field	Type	Description
closing_micro	integer
data	object
id	string
issued_at	string (date-time)
number	string
opening_micro	integer
period_end	string (date-time)
period_start	string (date-time)
sha256	string

GET/api/v1/orgs/{organization_id}/billing/statements/{statement_id}/pdf

Get Statement Pdf (getStatementPdf)

IAM action: billing:GetStatement

Parameter	In	Type	Description
organization_id required	path	string
statement_id required	path	string

Responses

• 200 The PDF (application/pdf)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

GET/api/v1/orgs/{organization_id}/billing/top-ups

List Top Ups (listTopUps)

IAM action: billing:ListTopUps

Parameter	In	Type	Description
organization_id required	path	string
limit	query	integer (nullable)
cursor	query	string (nullable)

Responses

• 200 OK (Page_TopUpOut_)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of Page_TopUpOut_

Field	Type	Description
items	array of TopUpOut
next_cursor	string (nullable)

POST/api/v1/orgs/{organization_id}/billing/top-ups

Create Top Up (createTopUp)

Start a payment. For M-Pesa (stk_push) the phone gets a PIN prompt; for Chapa (checkout, ETB or USD) send the payer to instruction.details.url. Then poll the top-up until it is succeeded, failed or expired.

IAM action: billing:CreateTopUp

Parameter	In	Type	Description
organization_id required	path	string

Request body (JSON, TopUpIn)

Field	Type	Description
amount required	string	In the currency, e.g. '500' or '500.00'.
currency	string	Default: "KES".
method	string	Default: "stk_push".
phone	string	M-Pesa: the paying phone number, e.g. 0712345678. Not used by Chapa. Default: "".
provider	string	Default: "mpesa".

Responses

• 201 Created (TopUpOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of TopUpOut

Field	Type	Description
amount_minor	integer
created_at	string (date-time)
currency	string
id	string
instruction	object (nullable)
method	string
payer	string
provider	string
provider_reference	string
rate	string (nullable)
state	string
status_message	string
updated_at	string (date-time)
usd_micro	integer (nullable)

GET/api/v1/orgs/{organization_id}/billing/top-ups/{topup_id}

Get Top Up (getTopUp)

IAM action: billing:GetTopUp

Parameter	In	Type	Description
organization_id required	path	string
topup_id required	path	string

Responses

• 200 OK (TopUpOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of TopUpOut

Field	Type	Description
amount_minor	integer
created_at	string (date-time)
currency	string
id	string
instruction	object (nullable)
method	string
payer	string
provider	string
provider_reference	string
rate	string (nullable)
state	string
status_message	string
updated_at	string (date-time)
usd_micro	integer (nullable)

GET/api/v1/orgs/{organization_id}/billing/top-ups/{topup_id}/receipt

Get Top Up Receipt (getTopUpReceipt)

The receipt of a succeeded top-up (404 until it has succeeded).

IAM action: billing:GetTopUp

Parameter	In	Type	Description
organization_id required	path	string
topup_id required	path	string

Responses

• 200 OK (object)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

GET/api/v1/orgs/{organization_id}/billing/top-ups/{topup_id}/receipt/pdf

Get Top Up Receipt Pdf (getTopUpReceiptPdf)

IAM action: billing:GetTopUp

Parameter	In	Type	Description
organization_id required	path	string
topup_id required	path	string

Responses

• 200 The PDF (application/pdf)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

GET/api/v1/orgs/{organization_id}/billing/transactions

List Transactions (listTransactions)

Newest first.

IAM action: billing:ListTransactions

Parameter	In	Type	Description
organization_id required	path	string
limit	query	integer (nullable)
cursor	query	string (nullable)

Responses

• 200 OK (Page_TransactionOut_)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of Page_TransactionOut_

Field	Type	Description
items	array of TransactionOut
next_cursor	string (nullable)

GET/api/v1/prices

List Prices (listPrices)

Prices in force now (USD per unit), upcoming changes, and included egress per VM.

IAM action: none (public, no sign-in)

Responses

• 200 OK (PriceListOut)
• 400 Invalid request (ErrorOut)
• 401 Not authenticated (ErrorOut)
• 403 Access denied: the error names the action and the resource (ErrorOut)
• 404 Not found (also: the resource belongs to another organization) (ErrorOut)
• 409 Conflict or quota exceeded (ErrorOut)
• 422 Idempotency key reused for a different request (ErrorOut)
• 429 Rate limited (ErrorOut)

Fields of PriceListOut

Field	Type	Description
at	string (date-time)
currency	string
egress_allowances	array of EgressAllowanceOut
hours_per_month	integer
prices	array of PriceOut
region	string
scheduled	array of PriceOut