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)

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

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

Provision sub-accounts via API with optional credit limits

Manage Sub-Accounts

Update credit limits, manage API keys, and monitor spending

Deletion & Deactivation

Deactivate sub-accounts and understand the deletion grace period

API Reference

Full API reference for sub-account endpoints

Getting Started

Concepts

Guides

Sub-Accounts

Sub-Accounts

How It Works

Key Concepts

Use Cases

SaaS Platforms

Agencies

Business Units

Resellers

Billing Model

Sub-Account vs Main Account API Keys

Next Steps

Create Sub-Accounts

Manage Sub-Accounts

Deletion & Deactivation

API Reference

​Sub-Accounts

​How It Works

​Key Concepts

​Use Cases

SaaS Platforms

Agencies

Business Units

Resellers

​Billing Model

​Sub-Account vs Main Account API Keys

​Next Steps

Create Sub-Accounts

Manage Sub-Accounts

Deletion & Deactivation

API Reference

Sub-Accounts

How It Works

Key Concepts

Use Cases

Billing Model

Sub-Account vs Main Account API Keys

Next Steps