> ## 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 in the EU, or send-us.ahasend.com as a US connection point forwarding to the EU. 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.

# ahasend subaccounts: Manage Sub-Accounts

> Create and manage AhaSend sub-accounts with the CLI, check pooled usage, suspend test accounts, and issue or revoke their scoped API keys.

AhaSend CLI sub-account commands let Platform Partners manage child accounts and their API keys from a parent account.

<Note>
  Sub-account creation is currently blocked by a CLI/API mismatch: the CLI requires a full website URL, while the API requires a bare domain. Wait for a compatible CLI/API release before running the create-first workflow below. The remaining management commands work with an existing sub-account; you can create one through the [API](/docs/api-reference/sub-accounts/create-sub-account).
</Note>

## Prerequisites

Use a [full parent-account API key](/docs/api-reference/authentication) with the matching [sub-account scopes](/docs/api-reference/scopes). Sub-accounts are available to [Platform Partners](/docs/scale/sub-accounts); [contact sales](mailto:sales@ahasend.com) about access. The shell examples need Bash and jq.

## Create and Manage a Test Sub-Account

After the creation issue above is fixed, save the following three examples in one Bash script. The script stops if creation fails, and only updates or deletes the test account it creates.

```bash theme={null}
set -euo pipefail
TEST_SUBACCOUNT_ID=$(ahasend subaccounts create --name "Docs test" --website https://example.com --monthly-credit 100 --output json | jq -er '.id')
ahasend subaccounts list
ahasend subaccounts get "$TEST_SUBACCOUNT_ID"
ahasend subaccounts update "$TEST_SUBACCOUNT_ID" --name "Docs updated test"
ahasend subaccounts suspend "$TEST_SUBACCOUNT_ID" --reason "Docs suspension test" --force
ahasend subaccounts unsuspend "$TEST_SUBACCOUNT_ID"
ahasend subaccounts usage
```

Usage `allocated_cost` is a proportional share of the parent's pooled invoice, not standalone pricing. A monthly credit of 0 means no cap.

## Manage a Test Sub-Account API Key

Continue with the sub-account created above. Store the one-time `secret_key` securely if an application needs it; this test keeps only the key ID.

```bash theme={null}
TEST_KEY_ID=$(ahasend subaccounts api-keys create "$TEST_SUBACCOUNT_ID" --label "Docs test key" --scope accounts:read --output json | jq -er '.id')
ahasend subaccounts api-keys list "$TEST_SUBACCOUNT_ID"
ahasend subaccounts api-keys get "$TEST_SUBACCOUNT_ID" "$TEST_KEY_ID"
ahasend subaccounts api-keys update "$TEST_SUBACCOUNT_ID" "$TEST_KEY_ID" --label "Docs updated key"
ahasend subaccounts api-keys delete "$TEST_SUBACCOUNT_ID" "$TEST_KEY_ID" --force
```

## Delete the Test Sub-Account

After the preceding create-first workflow, remove only its test account:

```bash theme={null}
ahasend subaccounts delete "$TEST_SUBACCOUNT_ID" --force
```

Deletion removes the sub-account from list results. Current billing-period usage still belongs to the parent invoice.

## Commands and Flags

### `subaccounts api-keys create`

```text theme={null}
ahasend subaccounts api-keys create <sub-account-id> [flags]
```

| Flag                       | Description and default                                           |
| -------------------------- | ----------------------------------------------------------------- |
| `--idempotency-key string` | Idempotency key for safe retries (auto-generated if not provided) |
| `--label string`           | Label for the API key (required)                                  |
| `--scope strings`          | Scopes to grant (required, can be used multiple times)            |

### `subaccounts api-keys delete`

```text theme={null}
ahasend subaccounts api-keys delete <sub-account-id> <key-id> [flags]
```

| Flag      | Description and default  |
| --------- | ------------------------ |
| `--force` | Skip confirmation prompt |

### `subaccounts api-keys get`

```text theme={null}
ahasend subaccounts api-keys get <sub-account-id> <key-id> [flags]
```

No command-specific flags. See [global flags](/docs/cli/configuration#global-flags).

### `subaccounts api-keys list`

```text theme={null}
ahasend subaccounts api-keys list <sub-account-id> [flags]
```

| Flag              | Description and default              |
| ----------------- | ------------------------------------ |
| `--cursor string` | Pagination cursor for next page      |
| `--limit int32`   | Maximum number of API keys to return |

### `subaccounts api-keys update`

```text theme={null}
ahasend subaccounts api-keys update <sub-account-id> <key-id> [flags]
```

| Flag              | Description and default                        |
| ----------------- | ---------------------------------------------- |
| `--label string`  | New label for the API key                      |
| `--scope strings` | New scopes to grant (replaces existing scopes) |

### `subaccounts create`

```text theme={null}
ahasend subaccounts create [flags]
```

| Flag                       | Description and default                                           |
| -------------------------- | ----------------------------------------------------------------- |
| `--idempotency-key string` | Idempotency key for safe retries (auto-generated if not provided) |
| `--monthly-credit int`     | Monthly credit allocation (0-1000000000)                          |
| `--name string`            | Sub-account name (required)                                       |
| `--website string`         | Sub-account website (required)                                    |

### `subaccounts delete`

```text theme={null}
ahasend subaccounts delete <sub-account-id> [flags]
```

| Flag      | Description and default  |
| --------- | ------------------------ |
| `--force` | Skip confirmation prompt |

### `subaccounts get`

```text theme={null}
ahasend subaccounts get <sub-account-id> [flags]
```

No command-specific flags. See [global flags](/docs/cli/configuration#global-flags).

### `subaccounts list`

```text theme={null}
ahasend subaccounts list [flags]
```

| Flag              | Description and default                  |
| ----------------- | ---------------------------------------- |
| `--cursor string` | Pagination cursor for next page          |
| `--limit int32`   | Maximum number of sub-accounts to return |

### `subaccounts suspend`

```text theme={null}
ahasend subaccounts suspend <sub-account-id> [flags]
```

| Flag              | Description and default              |
| ----------------- | ------------------------------------ |
| `--force`         | Skip confirmation prompt             |
| `--reason string` | Reason for the suspension (required) |

### `subaccounts unsuspend`

```text theme={null}
ahasend subaccounts unsuspend <sub-account-id> [flags]
```

No command-specific flags. See [global flags](/docs/cli/configuration#global-flags).

### `subaccounts update`

```text theme={null}
ahasend subaccounts update <sub-account-id> [flags]
```

| Flag                   | Description and default                      |
| ---------------------- | -------------------------------------------- |
| `--monthly-credit int` | New monthly credit allocation (0-1000000000) |
| `--name string`        | New sub-account name                         |
| `--website string`     | New sub-account website                      |

### `subaccounts usage`

```text theme={null}
ahasend subaccounts usage [flags]
```

No command-specific flags. See [global flags](/docs/cli/configuration#global-flags).

## Related Guides

* [Install the CLI](/docs/cli/installation), [CLI authentication](/docs/cli/authentication), [Sub-account setup](/docs/scale/sub-accounts).
* [Sub-account API rules](/docs/api-reference/sub-accounts/overview), [Child API keys](/docs/api-reference/sub-accounts/create-sub-account-api-key), [CLI configuration and output](/docs/cli/configuration).
* [API authentication](/docs/api-reference/authentication), [Permission scopes](/docs/api-reference/scopes).