Sub-Accounts

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

Create Sub-Account

TypeScript
const { subAccount } = await client.subAccounts.create({
  name: "Client ABC",
  externalId: "client_123",
  creditLimit: 100000, // $1,000.00 in cents
  metadata: {
    plan: "enterprise",
    region: "us-east",
  },
});

// Save this — only shown once
console.log(subAccount.apiKey);
console.log(subAccount.id);
console.log(subAccount.status); // active

Get Sub-Account

TypeScript
const { subAccount } = await client.subAccounts.retrieve({
  id: "jx7abc123def456",
});

console.log(subAccount.name);
console.log(subAccount.status);
console.log(subAccount.totalSpent);
console.log(subAccount.creditLimit);

List Sub-Accounts

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

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

// Paginate
const nextPage = await client.subAccounts.list({
  limit: 50,
  cursor: nextCursor,
});

Update Sub-Account

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

console.log(subAccount.creditLimit); // 200000

Suspend a Sub-Account

TypeScript
const { subAccount } = await client.subAccounts.update("jx7abc123def456", {
  status: "inactive",
});

// Re-activate later
const { subAccount: reactivated } = await client.subAccounts.update("jx7abc123def456", {
  status: "active",
});

Get Sub-Account Balance

TypeScript
const balance = await client.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)}`);
console.log(balance.isSubAccount); // true

Deactivate Sub-Account

TypeScript
const result = await client.subAccounts.deactivate("jx7abc123def456");
console.log(`Keys revoked: ${result.keysRevoked}`);

API Keys

List API Keys

TypeScript
const { items } = await client.subAccounts.apiKeys.list("jx7abc123def456");

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

Create API Key

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

// Save this — only shown once
console.log(apiKey.key);

Revoke API Key

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

Check Balance (Sub-Account Perspective)

When a sub-account uses its own API key, GET /v1/balance returns its spending data:

TypeScript
// Using a sub-account API key
const subClient = new Zavu({ apiKey: "zv_live_sub_xxxxxxxxxxxx" });
const balance = await subClient.balance.get();

console.log(balance.balance);      // team balance
console.log(balance.totalSpent);   // sub-account spending
console.log(balance.creditLimit);  // spending cap
console.log(balance.isSubAccount); // true