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

# Billing

> Understand plans, pricing, usage limits, and how MetrixLLM charges for usage.

MetrixLLM charges based on the volume of requests processed through the gateway. **We do not mark up model costs** — the money you pay to OpenAI, Anthropic, or Google for token usage is billed directly by those providers to the credit card you have on file with them.

MetrixLLM charges only for gateway compute, observability, and features like caching and routing.

## Plans overview

| Plan           | Monthly | Yearly | Requests/mo | Rate Limit | Seats     | Log Retention |
| -------------- | ------- | ------ | ----------- | ---------- | --------- | ------------- |
| **Free**       | \$0     | \$0    | 25,000      | 60/min     | 3         | 30 days       |
| **Pro**        | \$29    | \$290  | 500,000     | 300/min    | Unlimited | 90 days       |
| **Team**       | \$79    | \$790  | 2,000,000   | 600/min    | Unlimited | 365 days      |
| **Enterprise** | Custom  | Custom | Unlimited   | 5,000/min  | Unlimited | Custom        |

<Note>
  Yearly billing saves \~17% compared to monthly billing across all paid plans.
</Note>

## Plan features

### Free

Best for prototyping and side projects.

* Bring Your Own Key (BYOK) only — no native provider billing
* Basic cost analytics and status indicators
* Playground, shareable URLs, and code snippets
* Fallback routing enabled
* Standard community support

### Pro

For small teams shipping AI to production.

Everything in Free, plus:

* **Native billing** — no markup on provider costs
* **Smart caching** — semantic response deduplication
* **Rate limiting** — per-route request throttling
* **Budget limits** — per-request and monthly cost caps
* **Evaluations, guardrails, and datasets**
* **Prompt registry**
* **Normal roles** (Admin / Editor / Viewer)
* **IP allowlisting**
* Standard support

### Team

For growing teams with custom roles.

Everything in Pro, plus:

* **Custom roles** — granular RBAC with custom permission strings
* **Audit logs** — full activity trail for compliance
* **SSO** — SAML / OIDC integration
* Dedicated support

### Enterprise

For regulated and high-volume workloads.

Everything in Team, plus:

* **Unlimited requests** with 5,000 req/min rate limit
* **Custom data retention** policies
* **Dedicated engineer** for onboarding and support
* **SLA guarantee** with uptime commitments
* Custom pricing — [contact sales](mailto:sales@metrixllm.com)

## Feature comparison matrix

| Feature                    | Free | Pro | Team | Enterprise |
| -------------------------- | ---- | --- | ---- | ---------- |
| Native billing (no markup) | -    | Yes | Yes  | Yes        |
| Smart caching              | -    | Yes | Yes  | Yes        |
| Rate limiting              | -    | Yes | Yes  | Yes        |
| Budget limits              | -    | Yes | Yes  | Yes        |
| Fallback routing           | Yes  | Yes | Yes  | Yes        |
| Cost analytics             | Yes  | Yes | Yes  | Yes        |
| Sessions                   | Yes  | Yes | Yes  | Yes        |
| Evaluations                | -    | Yes | Yes  | Yes        |
| Guardrails                 | -    | Yes | Yes  | Yes        |
| Datasets                   | -    | Yes | Yes  | Yes        |
| Prompts                    | -    | Yes | Yes  | Yes        |
| Normal roles               | -    | Yes | Yes  | Yes        |
| Custom roles               | -    | -   | Yes  | Yes        |
| Audit logs                 | -    | -   | Yes  | Yes        |
| SSO (SAML/OIDC)            | -    | -   | Yes  | Yes        |
| IP allowlist               | -    | Yes | Yes  | Yes        |
| Playground                 | Yes  | Yes | Yes  | Yes        |
| Dedicated engineer         | -    | -   | -    | Yes        |
| SLA guarantee              | -    | -   | -    | Yes        |

## Usage limits

### Monthly request limit

Each plan includes a monthly request quota. Requests are counted at the gateway level — every call to `/v1/*` endpoints counts toward your limit.

| Plan       | Monthly Requests | Reset             |
| ---------- | ---------------- | ----------------- |
| Free       | 25,000           | 1st of each month |
| Pro        | 500,000          | 1st of each month |
| Team       | 2,000,000        | 1st of each month |
| Enterprise | Unlimited        | N/A               |

When the Free plan limit is exceeded, the gateway returns `402 Payment Required` errors. Upgrade to Pro to resume traffic.

### Rate limits

Rate limits are enforced per API key per minute:

| Plan       | Requests/minute |
| ---------- | --------------- |
| Free       | 60              |
| Pro        | 300             |
| Team       | 600             |
| Enterprise | 5,000           |

### Seat limits

| Plan       | Max Seats |
| ---------- | --------- |
| Free       | 3         |
| Pro        | Unlimited |
| Team       | Unlimited |
| Enterprise | Unlimited |

### Log retention

| Plan       | Retention |
| ---------- | --------- |
| Free       | 30 days   |
| Pro        | 90 days   |
| Team       | 365 days  |
| Enterprise | Custom    |

## Checking your usage

### Via the dashboard

Navigate to **Settings → Billing** to view:

* Current plan and tier
* Requests used this month vs. limit
* Current seat count
* Credit balance and spending

### Via the API

```bash theme={null}
curl https://api.metrixllm.com/api/plans/{workspaceId}/usage \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Response:

```json theme={null}
{
  "requests": {
    "used": 12450,
    "limit": 25000,
    "remaining": 12550,
    "resetAt": "2026-02-01T00:00:00.000Z"
  },
  "seats": {
    "used": 2,
    "limit": 3,
    "remaining": 1
  },
  "retention": {
    "days": 30
  }
}
```

## Upgrading your plan

<Steps>
  <Step title="Navigate to Billing">
    Go to **Settings → Billing** in your workspace.
  </Step>

  <Step title="Select a plan">
    Choose between Pro, Team, or Enterprise, and select monthly or yearly billing.
  </Step>

  <Step title="Complete checkout">
    You are redirected to our payment provider (Kelvinq) to enter payment details.
  </Step>

  <Step title="Plan activates">
    Once payment is confirmed, your workspace tier updates immediately and new features unlock.
  </Step>
</Steps>

<Note>
  Only workspace **owners** and **admins** can change plans.
</Note>

### Upgrade via API

```bash theme={null}
curl -X POST https://api.metrixllm.com/api/plans/{workspaceId}/checkout \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "billingCycle": "monthly"
  }'
```

This returns a `checkoutUrl` — redirect the user there to complete payment.

## Downgrading your plan

Downgrades take effect at the end of the current billing period. To downgrade:

1. Cancel your current subscription (it remains active until period end).
2. Subscribe to the new plan after cancellation.

<Warning>
  Downgrading may disable features your workspace relies on (e.g., custom roles, audit logs, IP allowlisting). Check the feature matrix before downgrading.
</Warning>

## Cancelling your plan

### Cancel at period end (default)

Your plan remains active until the current billing period ends, then downgrades to Free.

```bash theme={null}
curl -X POST https://api.metrixllm.com/api/plans/{workspaceId}/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"immediate": false}'
```

### Cancel immediately

Downgrades to Free right away.

```bash theme={null}
curl -X POST https://api.metrixllm.com/api/plans/{workspaceId}/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"immediate": true}'
```

<Warning>
  Immediate cancellation disables Pro+ features immediately. Your workspace reverts to Free tier limits.
</Warning>

## Managing your subscription

Use the customer portal to update payment methods, view invoices, and manage your subscription:

```bash theme={null}
curl -X POST https://api.metrixllm.com/api/plans/{workspaceId}/portal \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns a `portalUrl` — redirect the user there for self-service management.

## Credits and balance

Your workspace maintains a credit balance for usage-based billing:

* **Credits Allocated**: Total credits deposited (via checkout or manual adjustment).
* **Balance**: `creditsAllocated - totalSpent`, floored at zero.
* **Manual deposits**: Owners can add credits directly (admin adjustments).

### Autopay

Enable autopay to automatically recharge when your balance drops below a threshold:

| Setting            | Default | Description                            |
| ------------------ | ------- | -------------------------------------- |
| `autopayEnabled`   | false   | Toggle autopay on/off                  |
| `autopayThreshold` | \$10    | Recharge when balance drops below this |
| `autopayAmount`    | \$50    | Amount to charge on recharge           |

### Budget alerts

Configure email alerts to notify your team when spending reaches a threshold:

| Setting                | Default | Description                           |
| ---------------------- | ------- | ------------------------------------- |
| `budgetAlertEnabled`   | false   | Toggle alerts on/off                  |
| `budgetAlertThreshold` | \$10    | Alert when monthly spend exceeds this |
| `budgetAlertEmails`    | \[]     | List of email addresses to notify     |

## Billing API reference

| Endpoint                            | Method | Description                               |
| ----------------------------------- | ------ | ----------------------------------------- |
| `/api/plans`                        | GET    | List all plans with pricing and features  |
| `/api/plans/{workspaceId}/current`  | GET    | Get current plan, subscription, and usage |
| `/api/plans/{workspaceId}/checkout` | POST   | Create checkout session for upgrade       |
| `/api/plans/{workspaceId}/change`   | POST   | Change plan (upgrade/downgrade)           |
| `/api/plans/{workspaceId}/cancel`   | POST   | Cancel subscription                       |
| `/api/plans/{workspaceId}/portal`   | POST   | Create customer portal session            |
| `/api/plans/{workspaceId}/usage`    | GET    | Get detailed usage stats                  |

## Best practices

* **Monitor usage proactively** — Set budget alerts before hitting limits.
* **Choose yearly billing** if you're committed — saves \~17% across all paid plans.
* **Use the portal for payment updates** — Don't ask support to update card details; the portal handles it.
* **Check feature requirements before downgrading** — Losing custom roles or audit logs may break compliance workflows.

## Common pitfalls

<Warning>
  **Free plan seat limit is 3.** If you need more team members, you must upgrade to Pro or higher.
</Warning>

* **Downgrades are not instant.** They take effect at period end to avoid disrupting your service.
* **Request limits reset on the 1st of each month** (UTC). Plan upgrades take effect immediately.
* **Enterprise pricing is custom.** Contact sales for volume discounts and SLA details — pricing is not listed in the dashboard.
* **Free tier is BYOK only.** You must configure your own provider API keys. Pro+ supports native billing with no markup.