> ## 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.

# Creating Sub-Accounts

> Provision sub-accounts for your customers with API keys and spending controls

<Warning>
  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.
</Warning>

## Create a Sub-Account

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

### 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.

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

<Warning>
  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.
</Warning>

## 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      |

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

## External IDs

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

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

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

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Managing Sub-Accounts" icon="sliders" href="/guides/sub-accounts/managing">
    Update credit limits, rotate API keys, and monitor spending
  </Card>

  <Card title="Deletion & Deactivation" icon="trash" href="/guides/sub-accounts/deletion">
    Deactivate sub-accounts and understand the grace period
  </Card>
</CardGroup>