OpenMax
免费试用

Apps API · Billing History

Billing History: 9 个接口

← 全部分组

GET /api/v1/billing/addon-history

List agent add-on history

权限(scope): billing:usage:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
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

回包

GET /api/v1/billing/credit-statement

Get the credit statement

权限(scope): billing:usage:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
range_start query string (date-time) 是 Statement window start (RFC3339)
range_end query string (date-time) 是 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

回包

GET /api/v1/billing/invoices

List billing invoices

权限(scope): billing:order:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
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

回包

GET /api/v1/billing/orders

List billing orders

权限(scope): billing:order:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
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

回包

GET /api/v1/billing/orders/fate

Get an order's fate by idempotency key

权限(scope): billing:order:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
idempotency_key query string 是 The client-generated idempotency key the failed write carried

回包

GET /api/v1/billing/orders/{id}

Get a billing order

权限(scope): billing:order:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
id path string 是 Business order id (biz_order_id from the orders list / purchase response)

回包

GET /api/v1/billing/orders/{id}/checkout

Resume a pending order's checkout handle

权限(scope): billing:order:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
id path string 是 Business order id (biz_order_id from the orders list / purchase response)

回包

GET /api/v1/billing/orders/{id}/installments

Get the instalment / grant schedule of an order

权限(scope): billing:order:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
id path string 是 Business order id (biz_order_id from the orders list / purchase response)

回包

GET /api/v1/billing/usage-summary

Get metered usage aggregated to hour or day buckets

权限(scope): billing:usage:read · 调用方式: 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.

参数

名字 位置 类型 必填 说明
range_start query string (date-time) 是 Window start (RFC3339)
range_end query string (date-time) 是 Window end (RFC3339; hour granularity caps the range at 7 days, day at 92)
granularity query string: day, hour Bucket granularity (default day)

回包