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

​
Create Sub-Account

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
The api_key field is only included in the creation response. Store it securely.

​
Get Sub-Account

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

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

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

client.sub_accounts.update(
  "jx7abc123def456",
  status: "inactive"
)

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

​
Get Sub-Account Balance

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

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

​
API Keys

​
List API Keys

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

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

client.sub_accounts.revoke_api_key("jx7abc123def456", "key_id_here")