Managing Sub-Accounts

All endpoints under /v1/sub-accounts require a main account API key. A sub-account API key calling these endpoints receives HTTP 403. Sub-accounts can read their own balance via GET /v1/balance.

List Sub-Accounts

const { items, nextCursor } = await zavu.subAccounts.list({
  limit: 50,
});

for (const sub of items) {
  console.log(`${sub.name}: $${(sub.totalSpent / 100).toFixed(2)} spent`);
}

response = zavu.sub_accounts.list(limit=50)

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

curl https://api.zavu.dev/v1/sub-accounts?limit=50 \
  -H "Authorization: Bearer zv_live_xxx"

Update a Sub-Account

Update the name, credit limit, external ID, metadata, or status:

const { subAccount } = await zavu.subAccounts.update("jx7abc123def456", {
  creditLimit: 200000, // Increase to $2,000
  metadata: { plan: "enterprise-plus" },
});

sub_account = zavu.sub_accounts.update(
    "jx7abc123def456",
    credit_limit=200000,
    metadata={"plan": "enterprise-plus"},
)

curl -X PATCH https://api.zavu.dev/v1/sub-accounts/jx7abc123def456 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "creditLimit": 200000,
    "metadata": { "plan": "enterprise-plus" }
  }'

Updatable Fields

Field	Type	Description
`name`	string	Sub-account display name
`externalId`	string	Your reference ID
`creditLimit`	integer \| null	Spending cap in cents. Set to `null` or `0` to remove
`metadata`	object	Arbitrary key-value data
`status`	string	`"active"` or `"inactive"`

Monitor Spending

Check a Sub-Account’s Balance

const balance = await zavu.subAccounts.getBalance("jx7abc123def456");

console.log(`Team balance: $${(balance.balance / 100).toFixed(2)}`);
console.log(`Sub-account spent: $${(balance.totalSpent / 100).toFixed(2)}`);
console.log(`Credit limit: $${(balance.creditLimit / 100).toFixed(2)}`);

curl https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/balance \
  -H "Authorization: Bearer zv_live_xxx"

Response:

{
  "balance": 150000,
  "currency": "usd",
  "creditLimit": 100000,
  "totalSpent": 45000,
  "isSubAccount": true
}

Check Balance from the Sub-Account’s Perspective

When a sub-account uses its own API key to call GET /v1/balance, it sees the team balance plus its own spending data:

curl https://api.zavu.dev/v1/balance \
  -H "Authorization: Bearer zv_live_sub_xxxxxxxxxxxx"

{
  "balance": 150000,
  "currency": "usd",
  "creditLimit": 100000,
  "totalSpent": 45000,
  "isSubAccount": true
}

Manage API Keys

Each sub-account can have multiple API keys. Create additional keys or revoke compromised ones.

List API Keys

const { items } = await zavu.subAccounts.listApiKeys("jx7abc123def456");

for (const key of items) {
  console.log(`${key.name} (${key.keyPrefix}...): ${key.environment}`);
}

curl https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/api-keys \
  -H "Authorization: Bearer zv_live_xxx"

Create an API Key

const { apiKey } = await zavu.subAccounts.createApiKey("jx7abc123def456", {
  name: "Production Key",
  environment: "live",
});

// Save this — only shown once
console.log("New key:", apiKey.key);

curl -X POST https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/api-keys \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key", "environment": "live"}'

The full API key is only returned once in the creation response. Store it securely.

Revoke an API Key

await zavu.subAccounts.revokeApiKey("jx7abc123def456", "key_id_here");

curl -X DELETE https://api.zavu.dev/v1/sub-accounts/jx7abc123def456/api-keys/key_id_here \
  -H "Authorization: Bearer zv_live_xxx"

Revoked keys stop working immediately.

Suspend a Sub-Account

Set a sub-account’s status to inactive to temporarily block all messaging without revoking API keys:

curl -X PATCH https://api.zavu.dev/v1/sub-accounts/jx7abc123def456 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Re-activate later by setting status back to "active".

Next Steps

Deletion & Deactivation

Permanently deactivate sub-accounts

Sub-Accounts Concept

Understand the billing model and architecture

Getting Started

Concepts

Guides

Managing Sub-Accounts

List Sub-Accounts

Update a Sub-Account

Updatable Fields

Monitor Spending

Check a Sub-Account’s Balance

Check Balance from the Sub-Account’s Perspective

Manage API Keys

List API Keys

Create an API Key

Revoke an API Key

Suspend a Sub-Account

Next Steps

Deletion & Deactivation

Sub-Accounts Concept

​List Sub-Accounts

​Update a Sub-Account

​Updatable Fields

​Monitor Spending

​Check a Sub-Account’s Balance

​Check Balance from the Sub-Account’s Perspective

​Manage API Keys

​List API Keys

​Create an API Key

​Revoke an API Key

​Suspend a Sub-Account

​Next Steps

Deletion & Deactivation

Sub-Accounts Concept

List Sub-Accounts

Update a Sub-Account

Updatable Fields

Monitor Spending

Check a Sub-Account’s Balance

Check Balance from the Sub-Account’s Perspective

Manage API Keys

List API Keys

Create an API Key

Revoke an API Key

Suspend a Sub-Account

Next Steps