> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-sync-1774445910.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing API

> Manage subscriptions, check usage, enable BYOK, and purchase credits

# Billing API

Retrieve billing information and perform subscription actions such as creating a checkout session, enabling bring-your-own-key (BYOK) mode, checking usage, and purchasing credit packs.

<Note>All billing endpoints require session authentication.</Note>

## Get billing info

```http theme={null}
GET /api/billing
```

Returns the available plans, the authenticated user's current plan, subscription status, BYOK status, and daily usage.

### Response

```json theme={null}
{
  "plans": {
    "starter": {
      "name": "Starter",
      "price": 19,
      "dailyUnits": 600,
      "features": ["1 AI Agent", "2GB RAM", "Telegram", "Basic skills"]
    },
    "pro": {
      "name": "Pro",
      "price": 39,
      "dailyUnits": 1000,
      "features": ["1 AI Agent", "4GB RAM", "All channels", "All skills", "Priority support"]
    },
    "scale": {
      "name": "Scale",
      "price": 79,
      "dailyUnits": 2500,
      "features": ["3 AI Agents", "8GB RAM", "All channels", "All skills", "Analytics"]
    }
  },
  "currentPlan": "starter",
  "subscriptionStatus": "active",
  "byokEnabled": false,
  "usage": {
    "dailyUnits": 600,
    "used": 245,
    "remaining": 355
  }
}
```

### Response fields

| Field                | Type    | Description                                                                                                                                                                                                                               |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plans`              | object  | Map of available plans with pricing and features                                                                                                                                                                                          |
| `currentPlan`        | string  | User's current plan. One of `free`, `solo`, `collective`, `label`, `network`, `underground`, `starter`, `pro`, or `scale`. Users who subscribed via the Stripe checkout flow have plans like `solo`, `collective`, `label`, or `network`. |
| `subscriptionStatus` | string  | Stripe subscription status (`active`, `inactive`, etc.)                                                                                                                                                                                   |
| `byokEnabled`        | boolean | Whether BYOK mode is active                                                                                                                                                                                                               |
| `usage.dailyUnits`   | number  | Daily unit allowance for the current plan                                                                                                                                                                                                 |
| `usage.used`         | number  | Units used today                                                                                                                                                                                                                          |
| `usage.remaining`    | number  | Units remaining today                                                                                                                                                                                                                     |

<Note>The `currentPlan` value is set by the Stripe webhook when a checkout completes. Plans created through the primary checkout flow (`/api/stripe/checkout`) use `solo`, `collective`, `label`, or `network`. The billing dashboard displays these with their plan names: `solo` appears as "Solo", `collective` as "Collective", and `label` as "Label".</Note>

### Errors

| Code | Description                     |
| ---- | ------------------------------- |
| 401  | Unauthorized — no valid session |
| 500  | Failed to fetch billing info    |

## Billing actions

```http theme={null}
POST /api/billing
```

Performs a billing action. The `action` field in the request body determines which operation is executed.

### Create checkout session

Creates a Stripe checkout session for subscribing to a plan.

#### Request body

| Field    | Type   | Required | Description                                        |
| -------- | ------ | -------- | -------------------------------------------------- |
| `action` | string | Yes      | Must be `create-checkout`                          |
| `plan`   | string | Yes      | Plan to subscribe to: `starter`, `pro`, or `scale` |

#### Response

```json theme={null}
{
  "url": "https://checkout.stripe.com/c/pay/..."
}
```

Redirect the user to the returned `url` to complete payment.

#### Errors

| Code | Description  |
| ---- | ------------ |
| 400  | Invalid plan |

### Enable BYOK

Enables bring-your-own-key mode with an external AI provider. When BYOK is active, AI requests are billed directly by the provider rather than consuming platform credits.

#### Request body

| Field      | Type   | Required | Description                                        |
| ---------- | ------ | -------- | -------------------------------------------------- |
| `action`   | string | Yes      | Must be `enable-byok`                              |
| `apiKey`   | string | Yes      | Your API key for the external provider             |
| `provider` | string | Yes      | Provider name (for example, `openai`, `anthropic`) |

#### Response

```json theme={null}
{
  "success": true,
  "message": "BYOK enabled with openai. You'll pay openai directly for AI usage."
}
```

#### Errors

| Code | Description                       |
| ---- | --------------------------------- |
| 400  | API key and provider are required |

### Disable BYOK

Disables BYOK mode and reverts to platform credits.

#### Request body

| Field    | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `action` | string | Yes      | Must be `disable-byok` |

#### Response

```json theme={null}
{
  "success": true,
  "message": "BYOK disabled. Using platform credits."
}
```

### Get usage

Returns the current day's unit consumption.

#### Request body

| Field    | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `action` | string | Yes      | Must be `get-usage` |

#### Response

```json theme={null}
{
  "dailyUnits": 600,
  "used": 245,
  "remaining": 355,
  "resetsAt": "midnight UTC"
}
```

### Buy credits

Purchases a credit pack.

#### Request body

| Field    | Type   | Required | Description                      |
| -------- | ------ | -------- | -------------------------------- |
| `action` | string | Yes      | Must be `buy-credits`            |
| `pack`   | string | Yes      | Pack size: `50`, `200`, or `500` |

#### Response

```json theme={null}
{
  "success": true,
  "credits": 15,
  "price": "$15"
}
```

| Pack size | Credits |
| --------- | ------- |
| `50`      | 5       |
| `200`     | 15      |
| `500`     | 30      |

#### Errors

| Code | Description  |
| ---- | ------------ |
| 400  | Invalid pack |

### Common errors

These apply to all billing POST actions:

| Code | Description                     |
| ---- | ------------------------------- |
| 400  | Invalid action                  |
| 401  | Unauthorized — no valid session |
| 500  | Internal error                  |

## Stripe checkout

```http theme={null}
GET /api/stripe/checkout
```

Redirects to a Stripe checkout session for subscribing to a plan. This endpoint uses the `solo`, `collective`, `label`, and `network` plan names with GBP pricing. Admin users (configured via `ADMIN_EMAILS`) bypass Stripe and are redirected directly to the onboarding page.

<Note>The Stripe checkout plans (`solo`, `collective`, `label`, `network`) use different identifiers and GBP pricing from the billing API plans (`starter`, `pro`, `scale` with USD pricing). The checkout plans are the primary subscription path for agent provisioning. The billing dashboard displays checkout plan IDs with their plan names: `solo` as "Solo", `collective` as "Collective", and `label` as "Label".</Note>

### Query parameters

| Parameter | Type   | Required | Description                                                       |
| --------- | ------ | -------- | ----------------------------------------------------------------- |
| `plan`    | string | Yes      | Plan to subscribe to: `solo`, `collective`, `label`, or `network` |

### Checkout plan pricing

| Plan         | Price (GBP) |
| ------------ | ----------- |
| `solo`       | £29/mo      |
| `collective` | £69/mo      |
| `label`      | £149/mo     |
| `network`    | £499/mo     |

### Response

On success, redirects (303) to the Stripe checkout URL. On error, redirects to the pricing page with an error query parameter.

| Redirect                               | Description                        |
| -------------------------------------- | ---------------------------------- |
| Stripe checkout URL                    | Successful session creation        |
| `/pricing?error=invalid_plan`          | Unrecognized plan name             |
| `/pricing?error=stripe_not_configured` | Stripe secret key not set          |
| `/pricing?error=checkout_failed`       | Stripe API error                   |
| `/onboard?plan=...&paid=1&admin=1`     | Admin bypass (no payment required) |

## Subscription deploy

```http theme={null}
POST /api/subscriptions/deploy
```

Records a subscription-to-plan mapping so the next agent deployment uses the correct resource tier. This endpoint is called by the Stripe webhook after a checkout completes.

<Note>This is a backend-only endpoint that requires bearer token (API key) authentication.</Note>

### Request body

| Field              | Type   | Required    | Description                                                                                                                        |
| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `tier`             | string | Yes         | Plan tier. One of: `solo`, `collective`, `label`, `network`, `underground`, `starter`, `pro`, `scale`, `enterprise`, `white_glove` |
| `customerId`       | string | Conditional | Customer identifier. Either `customerId` or `stripeCustomerId` must be provided.                                                   |
| `stripeCustomerId` | string | Conditional | Stripe customer ID. Either `customerId` or `stripeCustomerId` must be provided.                                                    |
| `subscriptionId`   | string | No          | Stripe subscription ID                                                                                                             |

### Response

```json theme={null}
{
  "success": true,
  "customerId": "cus_abc123",
  "subscriptionId": "sub_xyz",
  "tier": "solo",
  "resources": {
    "memory": "2g",
    "cpus": "1"
  }
}
```

### Plan resource allocations

| Tier          | Memory | CPUs | Notes        |
| ------------- | ------ | ---- | ------------ |
| `solo`        | 2 GB   | 1    |              |
| `collective`  | 4 GB   | 2    |              |
| `label`       | 8 GB   | 4    |              |
| `network`     | 16 GB  | 4    |              |
| `underground` | 2 GB   | 1    | Legacy alias |
| `starter`     | 2 GB   | 1    | Legacy alias |
| `pro`         | 4 GB   | 2    | Legacy alias |
| `scale`       | 8 GB   | 4    | Legacy alias |
| `enterprise`  | 16 GB  | 4    | Legacy alias |
| `white_glove` | 32 GB  | 8    | Legacy alias |

### Errors

| Code | Description                                                           |
| ---- | --------------------------------------------------------------------- |
| 400  | `customerId` is required (when neither customer ID field is provided) |
| 400  | `tier` is required                                                    |
| 400  | Invalid tier                                                          |
| 401  | Unauthorized — missing or invalid bearer token                        |
| 500  | Subscription activation failed                                        |