Managing Sub-Accounts

List Sub-Accounts

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

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

Update a Sub-Account

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

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

Updatable Fields

Monitor Spending

Check a Sub-Account's Balance

TypeScriptcURLCopy
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)}`);

Response:

JSONCopy
{
  "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:

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

JSONCopy
{
  "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

TypeScriptcURLCopy
const { items } = await zavu.subAccounts.apiKeys.list("jx7abc123def456");

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

Create an API Key

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

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

Revoke an API Key

TypeScriptcURLCopy
// The key id comes first; the sub-account it belongs to is a param.
await zavu.subAccounts.apiKeys.revoke("key_id_here", { id: "jx7abc123def456" });

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:

terminalCopy
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