# Businesses

> The top-level container in Caramel: roles, tier gating, multi-business access, and what you cannot do via the API.

A business is the top-level container in Caramel. Every contact, form, campaign, template, and sender domain belongs to exactly one business. Every API call (except `caramel.v1.business.list`) takes a `business_id` to scope the operation.

## The business object

```json
{
  "id":                "bus_01h7m9k0aabcdefghj1234567",
  "name":              "Brewmaster Café",
  "slug":              "brewmaster-cafe",
  "subscription_tier": "growth",
  "currency":          "EUR",
  "locale":            "fr",
  "industry":          "restaurant",
  "role":              "owner",
  "created_at":        "2026-04-12T09:34:21Z"
}
```

| Field | Description |
|---|---|
| `id` | Stable identifier. Use this in every other call. |
| `name` | Human display name. Shown in the dashboard, in emails, on receipts. |
| `slug` | URL-safe handle for embed URLs (e.g. `/f/<form-slug>`). |
| `subscription_tier` | `starter` · `lite` · `growth` · `business` · `enterprise` · `lifetime`. Controls which API tools are available. |
| `currency` | Three-letter ISO 4217. Affects pricing on storefronts. |
| `locale` | Default language for templates and messages. `en` · `es` · `fr` · `de` · `it`. |
| `industry` | Drives template library filtering and AI generation defaults. |
| `role` | Your role on this business: `owner`, `manager`, or `employee`. |
| `created_at` | ISO 8601 timestamp. |

## List businesses

The first call most integrations make:

```bash
curl -X POST https://app.caramelme.com/api/functions/caramel-mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method":  "tools/call",
    "id":      1,
    "params":  { "name": "caramel.v1.business.list", "arguments": {} }
  }'
```

Cache this response — businesses don't change often. Re-fetch on `404 business_not_found` or once a day.

## Multi-business access

One OAuth token accesses every business the underlying user belongs to. Pass `business_id` per call to choose which one:

```js
const [businesses] = await listBusinesses();
const activeBusinessId = await uiSelectBusiness(businesses);
const forms = await listForms(activeBusinessId); // same token, different scope
```

Each call is checked server-side. If your user loses access to a business between `list_businesses` and a scoped call, the scoped call returns `403 forbidden`.

## Roles

Every business member has a role that gates which tools they can call.

| Role | Description |
|---|---|
| `owner` | Full control, including billing and destructive operations (`delete_campaign`). |
| `manager` | Operates campaigns and audiences. Cannot delete the business. |
| `employee` | Read-only access. Can submit forms. Cannot deploy or delete campaigns. |

Role boundaries are hard. A call you're not authorized for returns `403 forbidden` — there is no partial result. Design integrations for the minimum role you need; asking for owner access when manager suffices is a red flag for security reviews.

## Tier gating

The `subscription_tier` field controls which API tools are available. Tier is set at the business level and applies to every operation on that business.

| Tier | Available features |
|---|---|
| Starter | Forms, contacts, email, push |
| Lite | Expanded form limits, basic campaigns |
| Growth | SMS, WhatsApp, campaign library deploy |
| Business | Telegram, advanced journeys |
| Enterprise | Unlimited everything |
| Lifetime | Admin-granted; mirrors Business caps by default |

A downgrade takes effect immediately. The next call to a now-locked tool returns `403 tier_required`. Tier is also reported in `caramel.v1.meta.usage`.

> **Note** Tier changes happen through the dashboard or the billing flow — not through the public API. Your token remains valid across tier changes.

## Industry

The `industry` field drives:

- Which entries appear when you browse `list_template_library`.
- Which starter campaigns appear during onboarding.
- Default biasing when generating campaigns with AI.

Industry is set during signup. Observable changes show up in the next `caramel.v1.business.list` response.

## No business-creation API

Businesses are created through the signup flow at `caramelme.com/signup`. There is no public API for creating businesses. Billing setup, tax residency, and compliance items require user confirmation during signup — they cannot be satisfied programmatically.

If your product needs each of your customers to have their own Caramel business, redirect them to `caramelme.com/signup?from=<your_app_name>`. After signup, the OAuth flow connects their new business to your app.

> **Note** Programmatic business provisioning is on the roadmap for builder-tier accounts. If this blocks you, contact support — demand drives prioritization.

## Object relationships

Every object in the API belongs to one business. Templates, journeys, contacts, and forms created in business A are invisible to business B even if the same token can access both.

```
Business
   │
   ├── Contacts
   ├── Forms  ──► Submissions ──► Contacts
   ├── Campaigns (journeys + broadcasts)
   └── Templates
```

## Next steps

- [Forms and audience](forms-and-audience) — how contacts enter a business's audience
- [Campaigns and journeys](campaigns-and-journeys) — how campaigns are gated per tier
- [Authentication](../get-started/authentication) — how tokens are issued and scoped
- [Tools reference](../reference/tools) — the full list of callable tools