Tiers and scopes

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 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:

{
  "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 — per-tool parameter reference.
Errors — the tier_required, scope_required, and insufficient_credits error codes.
Authentication — requesting scopes in the OAuth flow.