Apps API · Billing History
Billing History: 9 endpoints
GET /api/v1/billing/addon-history
List agent add-on history
Scope: billing:usage:read · Called with: appToken · operationId: list-billing-addon-history
Required app scope: billing:usage:read.
Lists agent add-on purchase history (pure points, independent of orders). Page-based: fetch the next page by incrementing page while pagination.has_more is true. Any org member. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page |
query | integer (int32) | Page number (1-based; default: 1) | |
page_size |
query | integer (int32) | Items per page (omitted: server default, 50 for history lists, 100 for the credit statement; max 200) | |
order_by |
query | string | Sorting is not supported yet; any non-empty value is rejected with 400 |
Responses
200OK —application/json·BillingPageListResponseAddonHistoryDTOBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/credit-statement
Get the credit statement
Scope: billing:usage:read · Called with: appToken · operationId: get-billing-credit-statement
Required app scope: billing:usage:read.
Returns the credit activity (grants / canonical charge-backed consumptions / expiries / manual adjustments) for a bounded window (range capped at 92 days) plus the current balance. page/page_size window all four arrays together; has_more reports whether another page exists. Manual deductions are separate from consumption and usage totals; their points are positive magnitudes. Optional display_name/display_description are public copy; absent values use generic client labels. Any org member. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range_start |
query | string (date-time) | yes | Statement window start (RFC3339) |
range_end |
query | string (date-time) | yes | Statement window end (RFC3339; range capped at 92 days) |
page |
query | integer (int32) | Page number (1-based; default: 1) | |
page_size |
query | integer (int32) | Items per page (omitted: server default, 50 for history lists, 100 for the credit statement; max 200) | |
order_by |
query | string | Sorting is not supported yet; any non-empty value is rejected with 400 |
Responses
200OK —application/json·DataResponseCreditStatementDTOBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/invoices
List billing invoices
Scope: billing:order:read · Called with: appToken · operationId: list-billing-invoices
Required app scope: billing:order:read.
Lists invoices/receipts derived from settled fiat orders. Page-based: fetch the next page by incrementing page while pagination.has_more is true. has_more is exact: it is false on the last page, even when that page is exactly full. Admission follows intl_invoice_enabled: while the international invoice switch is off, any org member; while it is on, org-owner only (403 AUTH_FORBIDDEN otherwise, no rows returned). Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page |
query | integer (int32) | Page number (1-based; default: 1) | |
page_size |
query | integer (int32) | Items per page (omitted: server default, 50 for history lists, 100 for the credit statement; max 200) | |
order_by |
query | string | Sorting is not supported yet; any non-empty value is rejected with 400 |
Responses
200OK —application/json·ListInvoicesResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/orders
List billing orders
Scope: billing:order:read · Called with: appToken · operationId: list-billing-orders
Required app scope: billing:order:read.
Lists fiat order history (subscription / renewal / plan_change / credit_pack; add-ons excluded). Page-based: fetch the next page by incrementing page while pagination.has_more is true. Requires org-owner (403 AUTH_FORBIDDEN otherwise). Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page |
query | integer (int32) | Page number (1-based; default: 1) | |
page_size |
query | integer (int32) | Items per page (omitted: server default, 50 for history lists, 100 for the credit statement; max 200) | |
order_by |
query | string | Sorting is not supported yet; any non-empty value is rejected with 400 |
Responses
200OK —application/json·ListOrdersResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/orders/fate
Get an order's fate by idempotency key
Scope: billing:order:read · Called with: appToken · operationId: get-billing-order-fate
Required app scope: billing:order:read.
Returns the lifecycle fate (status + failure_code) of the order minted under the caller org's (org, idempotency_key) — the read-after-failure source of truth for the agent-purchase / credit-pack flows: after a write fails, a client reads server state here instead of interpreting the write-path error. Keyed by idempotency_key (a query selector), not the biz_order_id used by /orders/{id}. 404 (BILLING_ORDER_NOT_FOUND) when no order was minted under the key — the client can safely retry the write under the same key. org_id is taken from the caller's Principal. Requires org-owner (403 AUTH_FORBIDDEN otherwise). Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
idempotency_key |
query | string | yes | The client-generated idempotency key the failed write carried |
Responses
200OK —application/json·DataResponseOrderFateDTOBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/orders/{id}
Get a billing order
Scope: billing:order:read · Called with: appToken · operationId: get-billing-order
Required app scope: billing:order:read.
Returns a single fiat order by its business order id — the exact post-checkout confirmation lookup for the payment return page. An unknown id (or an order outside the caller's org) is 404. Requires org-owner (403 AUTH_FORBIDDEN otherwise). Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Business order id (biz_order_id from the orders list / purchase response) |
Responses
200OK —application/json·DataResponseOrderHistoryDTOBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/orders/{id}/checkout
Resume a pending order's checkout handle
Scope: billing:order:read · Called with: appToken · operationId: get-billing-order-checkout
Required app scope: billing:order:read.
Re-fetches the cashier URL for a pending fiat order so a client can resume an interrupted credit-pack or plan-change payment. status=pending_payment with a live handle returns checkout_url; status=expired means the handle is dead (cancel the order and create a new one). A transient payment-provider outage surfaces as an error (not swallowed). An unknown id (or an order outside the caller's org) is 404. Requires org-owner (403 AUTH_FORBIDDEN otherwise). Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Business order id (biz_order_id from the orders list / purchase response) |
Responses
200OK —application/json·DataResponseOrderCheckoutDTOBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/orders/{id}/installments
Get the instalment / grant schedule of an order
Scope: billing:order:read · Called with: appToken · operationId: get-billing-installment-schedule
Required app scope: billing:order:read.
Returns the per-instalment grant schedule of a multi-period purchase. Requires org-owner (403 AUTH_FORBIDDEN otherwise). An unknown id (or an order outside the caller's org) is 404. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Business order id (biz_order_id from the orders list / purchase response) |
Responses
200OK —application/json·DataResponseInstallmentScheduleDTOBodydefaultError —application/problem+json·D8Error
GET /api/v1/billing/usage-summary
Get metered usage aggregated to hour or day buckets
Scope: billing:usage:read · Called with: appToken · operationId: get-billing-usage-summary
Required app scope: billing:usage:read.
Aggregates metered usage to bucket_start × model × usage_type buckets. granularity=hour caps the range at 7 days (the 24h drill-down view); day (default) caps at 92 days (export source, statement parity). Each bucket reports quantity together with the unit code it is counted in (token|minute|request); unit is empty when the unit is unknown, and clients must then render the bare number rather than assuming one. Any org member. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range_start |
query | string (date-time) | yes | Window start (RFC3339) |
range_end |
query | string (date-time) | yes | Window end (RFC3339; hour granularity caps the range at 7 days, day at 92) |
granularity |
query | string: day, hour |
Bucket granularity (default day) |
Responses
200OK —application/json·DataResponseUsageSummaryDTOBodydefaultError —application/problem+json·D8Error
