# Tiers and scopes

> Which subscription tier and OAuth scope each Caramel API tool requires, plus AI credit consumption per operation.

Every tool has a minimum subscription tier and, for write operations, a required OAuth scope. A call from a lower tier returns `403 tier_required`. A call without the necessary scope returns `403 scope_required`.

## Tier order

```
Starter < Lite < Growth < Business < Enterprise
```

`Lifetime` is an admin-granted status that maps to the same access as Business for API purposes.

## Per-tool requirements

| Tool | Min tier | OAuth scope | AI credits |
|---|---|---|---|
| `caramel.v1.meta.capabilities` | Starter | _(any)_ | No |
| `caramel.v1.meta.usage` | Starter | _(any)_ | No |
| `list_businesses` | Starter | _(any)_ | No |
| `list_campaigns` | Starter | _(any)_ | No |
| `get_campaign` | Starter | _(any)_ | No |
| `get_campaign_suggestions` | Starter | _(any)_ | No |
| `delete_campaign` | Starter | _(any)_ | No |
| `caramel.v1.form.list` | Starter | `forms:read` | No |
| `caramel.v1.form.submit` | Starter | `forms:write` | No |
| `caramel.v1.template.list` | Starter | _(any)_ | No |
| `list_template_library` | Starter | _(any)_ | No |
| `caramel.v1.domain.status` | Starter | `provisioning:write` | No |
| `generate_campaign` | Growth | _(any)_ | Yes |
| `refine_campaign` | Growth | _(any)_ | Yes |
| `deploy_campaign` | Growth | _(any)_ | No |
| `pause_campaign` | Growth | _(any)_ | No |
| `resume_campaign` | Growth | _(any)_ | No |
| `deploy_template` | Growth | `provisioning:write` | No |
| `caramel.v1.contact.upsert` | Business | `audience:write` | No |

## Available OAuth scopes

| Scope | What it grants | Status |
|---|---|---|
| `meta:read` | Read tool capabilities and usage | Live |
| `forms:read` | List forms and read submission counts | Live |
| `forms:write` | Submit forms programmatically | Live |
| `audience:write` | Add and update contacts | Live |
| `provisioning:write` | Check domain status; deploy templates | Live |
| `audience:read` | List and search contacts | Coming soon |
| `messaging:send` | Send messages via email, SMS, WhatsApp | Coming soon |

Request scopes in the OAuth authorization URL when sending the user through the connect flow. Scopes not requested are unavailable even on a qualifying tier. See [Authentication](../get-started/authentication) for the full OAuth flow.

## Tier gates in detail

Tier is enforced server-side. Your app cannot bypass the gate by setting headers or calling a lower-level endpoint — the tools perform their own checks against the caller's business record.

Tools that consume AI credits additionally return `402 insufficient_credits` if the business has no credits left, even on a Growth-or-above tier. Tier is the first gate; credits are the second.

## AI credits

`generate_campaign` and `refine_campaign` each deduct credits from the business's monthly AI credit balance. Credits are allocated by tier each billing cycle.

| Tier | Monthly AI credits |
|---|---|
| Starter | 50 |
| Lite | 150 |
| Growth | 400 |
| Business | 1,000 |
| Enterprise | 3,000 |

One credit corresponds roughly to one generation or refinement iteration. Credit consumption scales with token usage:

| Token range | Credits per call |
|---|---|
| 0 – 1,999 tokens | 0.5 |
| 2,000 – 4,999 tokens | 1.0 |
| 5,000 – 9,999 tokens | 2.0 |
| 10,000+ tokens | 3.0 |

Check the remaining balance with `caramel.v1.meta.usage`. The response includes `ai_credits_remaining` and the tier limit.

> **Note** `get_campaign_suggestions` does not consume credits — it is a lightweight pre-generation advisory call available on all tiers.

## Discovering tier requirements at runtime

`caramel.v1.meta.capabilities` returns per-tool `tier_required` in its response. Query it at startup and cache the result rather than maintaining your own table:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "caramel.v1.meta.capabilities",
    "arguments": {}
  }
}
```

The structured response includes the current tier for the authenticated business, so you can gate your own UI against it.

## Next steps

- [Tools](tools) — per-tool parameter reference.
- [Errors](errors) — the `tier_required`, `scope_required`, and `insufficient_credits` error codes.
- [Authentication](../get-started/authentication) — requesting scopes in the OAuth flow.