Businesses

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

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

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:

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 — how contacts enter a business’s audience
• Campaigns and journeys — how campaigns are gated per tier
• Authentication — how tokens are issued and scoped
• Tools reference — the full list of callable tools