Billing

Expose the authenticated workspace's current credit position, billing period, metered usage, subscription posture, and purchasable product catalog without disclosing processor customer or subscription identifiers.

BUSINESS CASES

Where this module fits

credit and allowance monitoring
subscription and expiry review
period usage reconciliation
plan and top-up discovery

PRIMARY CONSUMERS

Who integrates it

account owners
finance teams
cost-management agents

PREREQUISITES

What must exist first

a bearer credential with billing:read
an active authenticated workspace whose identifier is bound by Identity

RECOMMENDED WORKFLOW

Compose the module safely.

01
read the billing account to establish the active period and credit-pool composition
02
read usage to compare rated and pending event totals
03
read products before presenting eligible plans or top-ups
04
treat invoices, hosted checkout, and portal-session creation as unavailable until those planned contracts enter the live OpenAPI document

MODULE CONTRACTS

Every mapped endpoint

Each operation states whether its request shape is authoritative in OpenAPI, reviewed as a planning profile, or intentionally left as an outline pending an owner schema.

GETGet billing account/api/v2/billing/accountReturn the authenticated workspace's credit balance, allowance, current-period consumption, credit-pool expiry behavior, active subscriptions, and settlement posture.›POSTCreate checkout/api/v2/billing/checkoutsPlanned capability: create a hosted checkout session for an eligible product.›GETList invoices/api/v2/billing/invoicesPlanned capability: list cursor-paginated billing invoices for the caller.›POSTCreate portal session/api/v2/billing/portal-sessionsPlanned capability: create a short-lived customer billing portal session.›GETList products/api/v2/billing/productsList active plans and non-expiring credit top-ups with exact minor-unit prices, currency, interval, and granted credit units.›GETGet usage/api/v2/billing/usageReturn aggregate metered credit usage, pending events, and reconciliation counters for the authenticated workspace's active billing period.›