Skip to main content
Sub-accounts let you provision isolated messaging environments for your customers with independent API keys and spending controls.

​
Create Sub-Account

result = client.sub_accounts.create(
    name="Client ABC",
    external_id="client_123",
    credit_limit=100000,  # $1,000.00 in cents
    metadata={
        "plan": "enterprise",
        "region": "us-east",
    },
)

# Save this — only shown once
print("API Key:", result.sub_account.api_key)
print("ID:", result.sub_account.id)
print("Status:", result.sub_account.status)  # active
The api_key field is only included in the creation response. Store it securely.

​
Get Sub-Account

result = client.sub_accounts.get(id="jx7abc123def456")

print(result.sub_account.name)
print(result.sub_account.status)
print(result.sub_account.total_spent)
print(result.sub_account.credit_limit)

​
List Sub-Accounts

result = client.sub_accounts.list(limit=50)

for sub in result.items:
    print(f"{sub.name}: ${sub.total_spent / 100:.2f} spent")

# Paginate
next_page = client.sub_accounts.list(
    limit=50,
    cursor=result.next_cursor,
)

​
Update Sub-Account

result = client.sub_accounts.update(
    "jx7abc123def456",
    credit_limit=200000,  # Increase to $2,000
    metadata={"plan": "enterprise-plus"},
)

print(result.sub_account.credit_limit)  # 200000

​
Suspend a Sub-Account

client.sub_accounts.update(
    "jx7abc123def456",
    status="inactive",
)

# Re-activate later
client.sub_accounts.update(
    "jx7abc123def456",
    status="active",
)

​
Get Sub-Account Balance

balance = client.sub_accounts.get_balance("jx7abc123def456")

print(f"Team balance: ${balance.balance / 100:.2f}")
print(f"Sub-account spent: ${balance.total_spent / 100:.2f}")
print(f"Credit limit: ${balance.credit_limit / 100:.2f}")
print(balance.is_sub_account)  # True

​
Deactivate Sub-Account

result = client.sub_accounts.deactivate("jx7abc123def456")
print(f"Keys revoked: {result.keys_revoked}")

​
API Keys

​
List API Keys

result = client.sub_accounts.list_api_keys("jx7abc123def456")

for key in result.items:
    print(f"{key.name} ({key.key_prefix}...): {key.environment}")

​
Create API Key

result = client.sub_accounts.create_api_key(
    "jx7abc123def456",
    name="Production Key",
    environment="live",
)

# Save this — only shown once
print("New key:", result.api_key.key)

​
Revoke API Key

client.sub_accounts.revoke_api_key("jx7abc123def456", "key_id_here")

​
Check Balance (Sub-Account Perspective)

When a sub-account uses its own API key, GET /v1/balance returns its spending data: 
# Using a sub-account API key
from zavudev import Zavu

sub_client = Zavu(api_key="zv_live_sub_xxxxxxxxxxxx")
balance = sub_client.balance.get()

print(balance.balance)        # team balance
print(balance.total_spent)    # sub-account spending
print(balance.credit_limit)   # spending cap
print(balance.is_sub_account) # True

​
Async Usage

import asyncio
from zavudev import AsyncZavudev

async def main():
    client = AsyncZavudev()

    result = await client.sub_accounts.create(
        name="Async Client",
        credit_limit=50000,
    )
    print(result.sub_account.id)
    print(result.sub_account.api_key)

asyncio.run(main())