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

# Credits, Auto-Recharge, and History

> Credit purchases, usage history, transactions, auto-recharge configuration, and billing history endpoints

# Credits, Auto-Recharge, and History

This endpoint group covers prepaid credit operations and billing observability.

## Endpoints

### Credits and purchases

* `POST /api/billing/:workspaceId/add-credits`
* `GET /api/billing/:workspaceId/credit-packages`
* `GET /api/billing/:workspaceId/transactions`

### Usage and history

* `GET /api/billing/:workspaceId/usage`
* `GET /api/billing/:workspaceId/usage-history`
* `GET /api/billing/:workspaceId/history`

### Auto-recharge

* `GET /api/billing/:workspaceId/auto-recharge`
* `PUT /api/billing/:workspaceId/auto-recharge`
* `POST /api/billing/:workspaceId/auto-recharge/payment-method`

## Permissions

* `billing:read`: read-only endpoints
* `billing:manage`: add credits and auto-recharge mutations

## Add credits payload

`POST /api/billing/:workspaceId/add-credits`

```json theme={null}
{
  "amountDollars": 50,
  "currency": "usd"
}
```

Validation:

* Amount must be finite number.
* Minimum: `$5`.
* Maximum single purchase: `$10,000`.
* Currency currently supports `usd` only.
* Amount is sanitized to cent precision before checkout creation.

## Usage endpoint

`GET /api/billing/:workspaceId/usage` returns:

* resource usage counts (links, rules, domains, campaigns, pixels, apiKeys)
* click/conversion usage for current cycle
* plan limits
* credit balance and cycle usage
* billing cycle dates and subscription status

The response is snapshot-cached for short TTL to reduce repeated analytics reads.

## Usage history endpoint

`GET /api/billing/:workspaceId/usage-history`

Query params:

* `start_date` (optional)
* `end_date` (optional)

Returns day-level credit cost breakdown (clicks, conversions, fraud checks, total).

## Auto-recharge payloads

`PUT /api/billing/:workspaceId/auto-recharge`

```json theme={null}
{
  "enabled": true,
  "thresholdDollars": 10,
  "amountDollars": 50
}
```

`POST /api/billing/:workspaceId/auto-recharge/payment-method`

```json theme={null}
{
  "paymentMethodId": "pm_xxx"
}
```

Enabling auto-recharge requires active subscription and saved payment method.

## Common errors

* `400`: invalid amount/currency/auto-recharge config/payment method
* `403`: missing permission
* `404`: workspace not found
* `500`: analytics/provider fetch failure