Sub-Accounts API Overview

Use the AhaSend Sub-Accounts API to provision isolated child accounts per customer, issue their API keys, suspend them, and track per-account usage and cost.

The AhaSend Sub-Accounts API reference covers child-account status values, parent credentials, permission scopes and retry rules.

Platform Partner feature: Sub-Accounts is part of our Platform Partner capabilities and is currently in early access. Contact us to enable it on your account.

For the product model and a complete setup example, use the sub-accounts guide.

All sub-account endpoints are addressed under the parent account ID, for example /v2/accounts/{account_id}/sub-accounts. The {account_id} path parameter is always the parent account, and {sub_account_id} identifies the child.

Sub-account status

Each sub-account reports a status field:

Status	Meaning
active	The sub-account is operating normally.
suspended	The sub-account was suspended directly via the suspend endpoint.
parent-suspended	The sub-account is suspended because its parent account is suspended.
deleted	The sub-account has been soft-deleted.

The monthly_credit field is an optional monthly cap on the sub-account, where 0 means no cap.

Parent and Child Credentials

Use a full parent API key for the sub-account endpoints. A child key uses the child account ID on ordinary v2 endpoints and cannot manage its own nested API keys. The setup guide walks through creation and safe storage of the one-time child secret.

Usage and billing

The usage endpoint returns current billing-period message volume and the proportional cost allocated to the parent and each active sub-account:

• allocation_method is proportional — each allocated_cost is a share of the parent’s pooled invoice for the period, distributed by message volume.
• allocated_cost is not standalone pricing. As the allocation_note disclaimer states, it reflects a proportional share of the parent’s pooled invoice, not what the sub-account would pay on its own plan.
• removed_sub_accounts aggregates usage from sub-accounts that were soft-deleted during the current period. That usage is still billed to the parent and is not attributed to individual sub-accounts.
• total is the combined parent, active sub-account, and removed-sub-account usage for the period.

Soft-deleted sub-accounts are excluded from the list endpoint. Usage they accrued before deletion in the current period is still reported through the removed_sub_accounts aggregate.

Idempotency

The create endpoints — create sub-account and create sub-account API key — accept an Idempotency-Key header for safe retries. Because the API-key create response carries a one-time secret_key, its idempotent replay is only available for 5 minutes; other create responses are replayable for 24 hours. See Request Idempotency for the full retry model.

Scopes

Sub-account operations require dedicated scopes, all granted to parent-account API keys:

Scope	Grants
sub-accounts:read	List and read sub-accounts
sub-accounts:write	Create and update sub-accounts
sub-accounts:delete	Soft-delete sub-accounts
sub-accounts:suspend	Suspend and unsuspend sub-accounts
sub-accounts:usage	Read per-sub-account usage and allocated cost
sub-account-api-keys:read	List and read sub-account API keys
sub-account-api-keys:write	Create and update sub-account API keys
sub-account-api-keys:delete	Delete sub-account API keys

See the Scopes reference for how scopes are evaluated.

Getting Started

Create a Sub-Account

Provision a new isolated child account under your parent account

Create a Sub-Account API Key

Issue a bootstrap key that authenticates as the child account

Sub-Account Usage

Track per-sub-account volume and allocated cost for the billing period

Scopes

Understand the scopes that control sub-account access

Related Guides

• API authentication, Permission scopes, Sub-account setup.
• Sub-account CLI, Child API keys, Idempotency rules.
• API errors, API rate limits, Plans and limits.