Accounts — Core API

List all accounts the authenticated user has access to

Retrieve an account by ID

Update an account's settings

List account credit ledger entries, most recent first

Usage-by-dimension billing rollup for a UTC month (YYYY-MM): the rated amount per pricing dimension (from the posted statement lines) plus the metered unit count, for reconciliation. Statement lines are posted by the monthly billing run; for an in-progress period the rated amounts may be empty while counts are still available.

Month-to-date view of the in-progress billing period (AUT-220), shaped by the period's billing profile:

• postpaid_subscription → estimate: true: live metered counts and capacity intervals dry-run through the same rating engine the monthly billing run uses, including the trial waiver. A projection, not a statement — nothing is written to the ledger, and late-arriving events may still shift the final statement.
• prepaid_credit → estimate: false: month-to-date actuals summed from the real-time credit-ledger draw-down (prepaid accounts are billed as usage happens; the monthly run skips them).

Use GET /v1/accounts/:id/usage?period=YYYY-MM for CLOSED periods — that reads the posted statement lines, which are the billable record.

Billed periods for the account, newest first — one row per period the monthly billing run has settled (AUT-220). Each row carries the settlement status (pending | settled | uncollectible | skipped), the signed period total (μUSD), and — when the period was settled through Stripe — the hosted_invoice_url (where the invoice is viewed and paid; open invoices can be paid there) and the invoice_pdf download link.

Link fields are fetched from the payment provider best-effort: the list still renders (with null links) if the provider is unreachable or the period settled without an external invoice (e.g. a no-charge trial month).

Settle an x402 payment and add prepaid credits to the account

Register an x402 payment method on the account. At most one active x402 method per account.

Implicit billing_mode change: billing_mode is derived from the count of active payment methods (gated when ≥1, ungated when 0), unless an operator override is set. Adding the first method on an account flips the derived billing_mode to "gated" automatically; removing the only method flips it back to "ungated". There is no public API to write billing_mode directly — operators with a need to pin it (e.g. force-ungated for a grandfathered customer) use the internal setGatingOverride RPC.

Stripe methods are not customer-creatable through this endpoint. Stripe binding requires a Setup Intent flow (not yet exposed); for now, AuthPI staff provision Stripe methods directly via internal tooling. Sending a Stripe payload here returns 400.

Start the add-card flow for Stripe billing (AUT-220). Returns a SetupIntent client_secret the console confirms with Stripe.js (card entry happens client-side; card data never touches AuthPI).

On successful confirmation, Stripe delivers setup_intent.succeeded to the AuthPI webhook, which provisions the account's Stripe payment method (at most one active per account — re-carding replaces the previous method). The saved card is then auto-charged by the monthly billing run; accounts without a card receive an emailed hosted invoice instead.

Returns 400 when Stripe payments are not configured for this environment.

Update mutable fields on a payment method (label, enabled state, x402 batching/restrictions). Disabling a method starts a 15-second grace window during which in-flight settlements still complete.

Soft-remove a payment method. Terminal — the method is retained in the list for audit but no longer accepted for settlements.