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

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

## Create Sub-Account

```ruby theme={null}
result = client.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
puts result.sub_account.api_key
puts result.sub_account.id
puts result.sub_account.status # active
```

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

## Get Sub-Account

```ruby theme={null}
result = client.sub_accounts.get(id: "jx7abc123def456")

puts result.sub_account.name
puts result.sub_account.status
puts result.sub_account.total_spent
puts result.sub_account.credit_limit
```

## List Sub-Accounts

```ruby theme={null}
result = client.sub_accounts.list(limit: 50)

result.items.each do |sub|
  puts "#{sub.name}: $#{'%.2f' % (sub.total_spent / 100.0)} spent"
end

# Paginate
next_page = client.sub_accounts.list(
  limit: 50,
  cursor: result.next_cursor
)
```

## Update Sub-Account

```ruby theme={null}
result = client.sub_accounts.update(
  "jx7abc123def456",
  credit_limit: 200000, # Increase to $2,000
  metadata: { "plan" => "enterprise-plus" }
)

puts result.sub_account.credit_limit # 200000
```

### Suspend a Sub-Account

```ruby theme={null}
client.sub_accounts.update(
  "jx7abc123def456",
  status: "inactive"
)

# Re-activate later
client.sub_accounts.update(
  "jx7abc123def456",
  status: "active"
)
```

## Get Sub-Account Balance

```ruby theme={null}
balance = client.sub_accounts.get_balance("jx7abc123def456")

puts "Team balance: $#{'%.2f' % (balance.balance / 100.0)}"
puts "Sub-account spent: $#{'%.2f' % (balance.total_spent / 100.0)}"
puts "Credit limit: $#{'%.2f' % (balance.credit_limit / 100.0)}"
puts balance.is_sub_account # true
```

## Deactivate Sub-Account

```ruby theme={null}
result = client.sub_accounts.deactivate("jx7abc123def456")
puts "Keys revoked: #{result.keys_revoked}"
```

## API Keys

### List API Keys

```ruby theme={null}
result = client.sub_accounts.list_api_keys("jx7abc123def456")

result.items.each do |key|
  puts "#{key.name} (#{key.key_prefix}...): #{key.environment}"
end
```

### Create API Key

```ruby theme={null}
result = client.sub_accounts.create_api_key(
  "jx7abc123def456",
  name: "Production Key",
  environment: "live"
)

# Save this — only shown once
puts "New key: #{result.api_key.key}"
```

### Revoke API Key

```ruby theme={null}
client.sub_accounts.revoke_api_key("jx7abc123def456", "key_id_here")
```