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

# Sub-Accounts

> Isolate messaging for your customers with independent API keys and spending controls

# Sub-Accounts

Sub-accounts let you create **isolated messaging environments** for your customers, clients, or business units — each with their own API key, spending limits, and usage tracking. All charges are billed to your team's balance.

## How It Works

Every team has one **main account** (your primary project) and can create multiple **sub-accounts**. Sub-accounts share your team's **balance**, but are fully isolated — each has its own API keys, senders, phone numbers, contacts, and usage tracking.

```
Team (Balance: $500)
├── Main Account (your project)
├── Sub-Account: Client ABC (totalSpent: $45, creditLimit: $100)
├── Sub-Account: Client XYZ (totalSpent: $120, creditLimit: $200)
└── Sub-Account: Partner Co  (totalSpent: $30, no limit)
```

<Warning>
  Each team can have **only one main account**. All additional projects must be sub-accounts. If you need another main account, create a new team.
</Warning>

## Key Concepts

| Concept            | Description                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Main Account**   | Your primary project. One per team. Can create and manage sub-accounts.                                                   |
| **Sub-Account**    | A fully isolated project with its own API keys, senders, phone numbers, and contacts. Created via the main account's API. |
| **Credit Limit**   | Optional spending cap in cents. Messages are blocked when reached.                                                        |
| **Total Spent**    | Running total of all charges for the sub-account, in cents.                                                               |
| **Shared Balance** | All sub-accounts draw from the team's balance. There are no separate sub-account balances.                                |

## Use Cases

<CardGroup cols={2}>
  <Card title="SaaS Platforms" icon="building">
    Give each of your customers their own API key with independent spending limits. Track usage per customer for billing.
  </Card>

  <Card title="Agencies" icon="users">
    Manage multiple client accounts under one team. Set credit limits to control spending per client.
  </Card>

  <Card title="Business Units" icon="sitemap">
    Separate messaging for different departments or product lines while sharing the same balance.
  </Card>

  <Card title="Resellers" icon="handshake">
    Provision accounts for downstream customers with their own API keys and usage tracking.
  </Card>
</CardGroup>

## Billing Model

Sub-accounts don't have their own balance. All charges are deducted from the **parent team's balance**:

```
Customer sends message via sub-account API key
      ↓
Zavu charges the message cost
      ↓
Team balance decreases
Sub-account totalSpent increases
      ↓
If totalSpent >= creditLimit → messages blocked
```

<Info>
  The `GET /v1/balance` endpoint returns different data depending on the API key used. A sub-account API key includes `isSubAccount: true`, `totalSpent`, and `creditLimit` in the response.
</Info>

## Sub-Account vs Main Account API Keys

Both types of API keys can send messages, manage contacts, and use all messaging features. The differences:

| Feature                               | Main Account | Sub-Account |
| ------------------------------------- | ------------ | ----------- |
| Send messages                         | Yes          | Yes         |
| Manage contacts                       | Yes          | Yes         |
| Create sub-accounts                   | Yes          | No          |
| Manage sub-accounts                   | Yes          | No          |
| Credit limit enforcement              | No           | Yes         |
| Usage tracking (`totalSpent`)         | No           | Yes         |
| Balance endpoint shows `isSubAccount` | `false`      | `true`      |

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Sub-Accounts" icon="plus" href="/guides/sub-accounts/creating">
    Provision sub-accounts via API with optional credit limits
  </Card>

  <Card title="Manage Sub-Accounts" icon="sliders" href="/guides/sub-accounts/managing">
    Update credit limits, manage API keys, and monitor spending
  </Card>

  <Card title="Deletion & Deactivation" icon="trash" href="/guides/sub-accounts/deletion">
    Deactivate sub-accounts and understand the deletion grace period
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/sub-accounts/create-sub-account">
    Full API reference for sub-account endpoints
  </Card>
</CardGroup>