> ## Documentation Index > Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > AhaSend stores all message data in the EU. See /facts. > The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication. > Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp. > For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes. # Sub-Accounts API Overview > Use the AhaSend Sub-Accounts API to provision isolated child accounts per customer, issue their API keys, pause 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. > [!NOTE] > > **Plan availability:** sub-accounts are included on Pro (up to 9) and Max (no limit). There is no charge per sub-account; the volume of all sub-accounts is pooled on the parent's plan. See [plans and features](https://ahasend.com/docs/facts.md#plans-and-features). For the product model and a complete setup example, use the [sub-accounts guide](https://ahasend.com/docs/scale/sub-accounts.md). > [!NOTE] > > 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` | Sending is paused on the sub-account. The parent account can pause it with the [pause endpoint](https://ahasend.com/docs/api-reference/sub-accounts/suspend-sub-account.md). AhaSend can also [pause it](https://ahasend.com/docs/troubleshooting.md#why-is-sending-paused-on-my-account). | | `parent-suspended` | Sending is paused on the parent account, so the sub-account cannot send. | | `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](https://ahasend.com/docs/api-reference/authentication.md) 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](https://ahasend.com/docs/scale/sub-accounts.md) walks through creation and safe storage of the one-time child secret. ## Usage and billing The [usage endpoint](https://ahasend.com/docs/api-reference/sub-accounts/get-sub-accounts-usage.md) 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. > [!NOTE] > > Soft-deleted sub-accounts are excluded from [the list endpoint](https://ahasend.com/docs/api-reference/sub-accounts/get-sub-accounts.md). 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](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account.md) and [create sub-account API key](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account-api-key.md) — accept an [`Idempotency-Key`](https://ahasend.com/docs/api-reference/idempotency) 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](https://ahasend.com/docs/api-reference/idempotency.md) 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` | Pause and resume sub-accounts, and unpause their domains | | `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](https://ahasend.com/docs/api-reference/scopes.md#sub-account-management) for how scopes are evaluated. ## Getting Started > [card] [Create a Sub-Account](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account.md) > > Provision a new isolated child account under your parent account > [card] [Create a Sub-Account API Key](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account-api-key.md) > > Issue a bootstrap key that authenticates as the child account > [card] [Sub-Account Usage](https://ahasend.com/docs/api-reference/sub-accounts/get-sub-accounts-usage.md) > > Track per-sub-account volume and allocated cost for the billing period > [card] [Scopes](https://ahasend.com/docs/api-reference/scopes.md) > > Understand the scopes that control sub-account access ## Related Guides * [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md), [Sub-account setup](https://ahasend.com/docs/scale/sub-accounts.md). * [Sub-account CLI](https://ahasend.com/docs/cli/commands/subaccounts.md), [Child API keys](https://ahasend.com/docs/api-reference/sub-accounts/create-sub-account-api-key.md), [Idempotency rules](https://ahasend.com/docs/api-reference/idempotency.md). * [API errors](https://ahasend.com/docs/api-reference/errors.md), [API rate limits](https://ahasend.com/docs/api-reference/rate-limits.md), [Plans and limits](https://ahasend.com/docs/facts.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.