Skip to main content

​
Billing API

Billing is workspace-scoped and covers plan lifecycle plus credit balance operations.

​
Authentication model

  • Session auth required (/billing/* is not API-key accessible).
  • workspaceId path must match an accessible workspace.
  • Permission checks are applied per route (billing:read / billing:manage).

​
Endpoint matrix

​
Subscription and plans

  • GET /billing/plans
  • GET /billing/:workspaceId
  • POST /billing/:workspaceId/subscribe
  • POST /billing/:workspaceId/change-plan
  • POST /billing/:workspaceId/cancel
  • POST /billing/:workspaceId/reactivate
  • GET /billing/:workspaceId/portal

​
Credits and top-up

  • POST /billing/:workspaceId/add-credits
  • GET /billing/:workspaceId/credit-packages
  • GET /billing/:workspaceId/transactions

​
Auto-recharge

  • GET /billing/:workspaceId/auto-recharge
  • PUT /billing/:workspaceId/auto-recharge
  • POST /billing/:workspaceId/auto-recharge/payment-method

​
Usage and history

  • GET /billing/:workspaceId/usage
  • GET /billing/:workspaceId/usage-history
  • GET /billing/:workspaceId/history

​
Data model highlights

  • Monetary balances are represented in micro-dollars internally and converted for display.
  • Usage aggregates combine click/conversion analytics with fraud-check cost accounting.
  • History combines Stripe invoice records with billing-relevant credit transactions.

​
Auto-recharge behavior

To enable auto-recharge:
  • workspace needs active subscription/customer context
  • a payment method must be configured
  • threshold/amount validation is enforced on update

​
Caching behavior

High-read usage endpoints (/usage, /usage-history) are snapshot-cached briefly to reduce repeated analytics load.

​
Typical failures

  • 404 NOT_FOUND workspace missing/inaccessible
  • 400 invalid plan/period/payment setup
  • 403 permission denied
  • 500 upstream billing provider or analytics fetch errors
Related docs:
  • /api-reference/billing/subscriptions-and-plan-lifecycle
  • /api-reference/billing/credits-auto-recharge-and-history
  • /user-guides/manual/monetization/billing-plans-and-credits
  • /user-guides/manual/monetization/billing-plans-and-credits
  • /user-guides/manual/monetization/plans-pricing-and-limits-reference