> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing API

> Workspace billing state, subscriptions, credits, auto-recharge, usage analytics, and billing history

# 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`