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

# Billing & Credits

> Manage subscriptions, purchase credits, and understand pricing

## CLI First

```bash theme={"theme":"css-variables"}
# Plan + subscription
naive billing plans
naive billing subscribe --plan starter

# Check current status
naive billing status
```

## Plans

| Plan        | Price    | Credits/Month | Features                                         |
| ----------- | -------- | ------------- | ------------------------------------------------ |
| **Starter** | \$49/mo  | 500           | All primitives, system email domain              |
| **Pro**     | \$149/mo | 2000          | All primitives, custom domains, priority support |

First-time subscribers get a **7-day free trial** with 1 credit.

## Credit Packs

One-time purchases — credits are added immediately after payment and never expire.

| Pack   | Credits | Price | Per Credit |
| ------ | ------- | ----- | ---------- |
| Small  | 200     | \$10  | \$0.05     |
| Medium | 500     | \$23  | \$0.05     |
| Large  | 1000    | \$44  | \$0.04     |
| XL     | 2500    | \$100 | \$0.04     |

<Info>Larger packs are more cost-effective. Credits never expire.</Info>

## Subscribe to a Plan

<CodeGroup>
  ```bash CLI theme={"theme":"css-variables"}
  naive billing subscribe --plan starter
  ```

  ```bash cURL theme={"theme":"css-variables"}
  curl -X POST https://api.usenaive.ai/v1/billing/subscribe \
    -H "Authorization: Bearer nv_sk_..." \
    -H "Content-Type: application/json" \
    -d '{"plan": "starter"}'
  ```
</CodeGroup>

Returns a checkout URL. Open it to complete payment, then verify:

```bash theme={"theme":"css-variables"}
naive billing status
```

## Buy More Credits

<CodeGroup>
  ```bash CLI theme={"theme":"css-variables"}
  naive billing topup --pack medium
  ```

  ```bash cURL theme={"theme":"css-variables"}
  curl -X POST https://api.usenaive.ai/v1/billing/topup \
    -H "Authorization: Bearer nv_sk_..." \
    -H "Content-Type: application/json" \
    -d '{"pack_id": "medium"}'
  ```
</CodeGroup>

## Upgrade Your Plan

<CodeGroup>
  ```bash CLI theme={"theme":"css-variables"}
  naive billing upgrade --plan pro
  ```

  ```bash cURL theme={"theme":"css-variables"}
  curl -X POST https://api.usenaive.ai/v1/billing/upgrade \
    -H "Authorization: Bearer nv_sk_..." \
    -H "Content-Type: application/json" \
    -d '{"plan": "pro"}'
  ```
</CodeGroup>

If you have an active subscription, this opens the billing portal where you can change plans with automatic proration.

## Check Billing Status

```bash theme={"theme":"css-variables"}
naive billing status
```

Returns your current plan, subscription status, credits remaining, and period end date.

## What Happens When You Run Out

### Billing Blocked (no active subscription)

If your trial expires or subscription is cancelled, all operations are blocked. The error response includes available plans:

```json theme={"theme":"css-variables"}
{
  "error": {
    "code": "billing_blocked",
    "message": "Your free trial has expired. Subscribe to continue.",
    "block_reason": "trial_expired",
    "plans": [
      { "id": "starter", "credits_per_month": 500, "price": "$49/mo" },
      { "id": "pro", "credits_per_month": 2000, "price": "$149/mo" }
    ]
  }
}
```

### Insufficient Credits (balance exhausted)

If you have an active subscription but no credits left, operations fail with available credit packs:

```json theme={"theme":"css-variables"}
{
  "error": {
    "code": "insufficient_credits",
    "message": "Credit balance exhausted.",
    "packs": [
      { "id": "small", "credits": 200, "price": "$10" },
      { "id": "medium", "credits": 500, "price": "$23" },
      { "id": "large", "credits": 1000, "price": "$44" },
      { "id": "xl", "credits": 2500, "price": "$100" }
    ]
  }
}
```

## Manage Subscription

Open the billing portal to update payment method, change plans, or cancel:

```bash theme={"theme":"css-variables"}
naive billing portal
```