> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-Accounts

> Manage sub-accounts with the TypeScript SDK

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

## Create Sub-Account

```typescript theme={null}
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
```

<Warning>
  The `apiKey` field is only included in the creation response. Store it securely.
</Warning>

## Get Sub-Account

```typescript theme={null}
const { subAccount } = await client.subAccounts.get({
  id: "jx7abc123def456",
});

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

## List Sub-Accounts

```typescript theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
const result = await client.subAccounts.deactivate("jx7abc123def456");
console.log(`Keys revoked: ${result.keysRevoked}`);
```

## API Keys

### List API Keys

```typescript theme={null}
const { items } = await client.subAccounts.listApiKeys("jx7abc123def456");

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

### Create API Key

```typescript theme={null}
const { apiKey } = await client.subAccounts.createApiKey("jx7abc123def456", {
  name: "Production Key",
  environment: "live",
});

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

### Revoke API Key

```typescript theme={null}
await client.subAccounts.revokeApiKey("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:

```typescript theme={null}
// 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
```