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.

Code
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)

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:

Code
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

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