# Sub-Accounts

> Isolate messaging for your customers with sub-accounts: independent API keys, spend limits, routing and reporting per tenant.

## 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.

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

  - **SaaS Platforms**: Give each of your customers their own API key with independent spending limits. Track usage per customer for billing.
  - **Agencies**: Manage multiple client accounts under one team. Set credit limits to control spending per client.
  - **Business Units**: Separate messaging for different departments or product lines while sharing the same balance.
  - **Resellers**: Provision accounts for downstream customers with their own API keys and usage tracking.

## 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.

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

  - [Create Sub-Accounts](https://www.zavu.dev/docs/guides/sub-accounts/creating): Provision sub-accounts via API with optional credit limits
  - [Manage Sub-Accounts](https://www.zavu.dev/docs/guides/sub-accounts/managing): Update credit limits, manage API keys, and monitor spending
  - [Deletion & Deactivation](https://www.zavu.dev/docs/guides/sub-accounts/deletion): Deactivate sub-accounts and understand the deletion grace period
  - [API Reference](https://www.zavu.dev/docs/api-reference/sub-accounts/create-sub-account): Full API reference for sub-account endpoints