payments

Base path: /api/v1/payments

The payments module is the billing surface backed by Stripe. It covers subscription create and cancel, plan switching, billing portal sessions, and read-only credit usage telemetry. The actual upgrade flow stays in the UI so checkout PCI exposure is bounded; programmatic clients can read plan and credits but cannot mutate billing. Resources include subscriptions, plans, billing portal sessions, invoices, and credit ledgers. Schemas live in app/modules/payments/schemas.py.

What you can do with the payments API

• Read your current plan, included credits, and remaining usage
• Inspect recent invoices and their statuses
• Open a Stripe billing portal session for a customer to manage card or address
• Read credit consumption per agent or per workspace
• Receive subscription.updated and invoice.paid events via webhooks

Common operations

• Get the current subscription with plan name, renewal date, and status
• Get this period’s credit usage against the plan cap
• Generate a billing portal URL for a logged-in admin
• List the last N invoices for a finance export
• Subscribe to billing webhooks for in-app upgrade prompts

Authentication & scoping

Workspace-scoped via API key in the Authorization: Bearer tnx_... header. Mutations like create-subscription, change-plan, and cancel are restricted to UI flows; the API exposes the read paths and the portal session.

Pagination & filtering

Invoice and ledger list endpoints paginate cursor-style. See Pagination.

How credit accounting works

Every agent run debits credits according to the agent’s tier and the actual token spend. Credit usage rolls up to the workspace level, with a soft cap (warnings) and a hard cap (refusal to start new runs). Read both caps via the plan endpoint so your UI can prompt before the hard cap.

MCP equivalents

Related

• Concepts: Credits and usage
• dashboard for usage rollups across agents
• Webhooks for billing event delivery