Creating Sub-Accounts

You must use a main account API key to create sub-accounts. Sub-account API keys cannot create new sub-accounts (no nesting) and receive HTTP 403 if they try.

Create a Sub-Account

import Zavu from "@zavudev/sdk";

const zavu = new Zavu({ apiKey: "zv_live_xxx" });

const { subAccount } = await zavu.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("API Key:", subAccount.apiKey);

from zavudev import Zavu

zavu = Zavu(api_key="zv_live_xxx")

sub_account = zavu.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:", sub_account.api_key)

curl -X POST https://api.zavu.dev/v1/sub-accounts \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client ABC",
    "externalId": "client_123",
    "creditLimit": 100000,
    "metadata": {
      "plan": "enterprise",
      "region": "us-east"
    }
  }'

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the sub-account (max 200 characters)
`externalId`	string	No	Your own reference ID for tracking
`creditLimit`	integer	No	Spending cap in cents. `0` or omitted = no limit
`metadata`	object	No	Arbitrary key-value pairs for your own use

Response

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

{
  "subAccount": {
    "id": "jx7abc123def456",
    "name": "Client ABC",
    "externalId": "client_123",
    "status": "active",
    "totalSpent": 0,
    "creditLimit": 100000,
    "metadata": {
      "plan": "enterprise",
      "region": "us-east"
    },
    "apiKey": "zv_live_sub_xxxxxxxxxxxx",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

The apiKey field is only included in the creation response. If you lose it, you’ll need to create a new API key for the sub-account.

Credit Limits

Credit limits act as a spending cap in cents. When a sub-account’s totalSpent reaches the creditLimit, all messaging is blocked.

Credit Limit	Behavior
Omitted or `0`	No spending cap — uses full team balance
`100000`	Blocks messaging after $1,000.00 spent
`500`	Blocks messaging after $5.00 spent

Credit limits protect your balance from unexpected usage. You can update or remove them at any time via PATCH /v1/sub-accounts/:id.

External IDs

The externalId field lets you map sub-accounts to your own system:

// Create with your internal customer ID
const { subAccount } = await zavu.subAccounts.create({
  name: "Acme Corp",
  externalId: "cust_abc123", // Your CRM customer ID
});

This is useful for:

Mapping sub-accounts to your CRM records
Billing reconciliation
Audit trails

Metadata

Store arbitrary key-value data with the sub-account:

const { subAccount } = await zavu.subAccounts.create({
  name: "Client ABC",
  metadata: {
    plan: "enterprise",
    billingEmail: "billing@client-abc.com",
    salesRep: "jane@yourcompany.com",
  },
});

One Main Account Rule

Each team is limited to one main account. All additional projects must be sub-accounts.

Team "My Company"
├── Main Account ← created automatically when the team is created
├── Sub-Account: Client A ✓
├── Sub-Account: Client B ✓
└── Main Account ✗ (rejected — use a sub-account or create a new team)

If you try to create a second main account, the API returns an error:

{
  "code": "invalid_request",
  "message": "Team already has a main account. Create a sub-account instead, or create a new team for another main account."
}

Getting Started

Concepts

Guides

Creating Sub-Accounts

Create a Sub-Account

Parameters

Response

Credit Limits

External IDs

Metadata

One Main Account Rule

Next Steps

Managing Sub-Accounts

Deletion & Deactivation

​Create a Sub-Account

​Parameters

​Response

​Credit Limits

​External IDs

​Metadata

​One Main Account Rule

​Next Steps

Managing Sub-Accounts

Deletion & Deactivation

Create a Sub-Account

Parameters

Response

Credit Limits

External IDs

Metadata

One Main Account Rule

Next Steps