> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing usage and settings

> Read current usage and manage your organization's overage limit and email footer

Use an [admin-scoped API key](/docs/api-keys) for these endpoints. Agent-scoped keys receive `403`. You can also manage billing in the [Inkbox Console](https://inkbox.ai/console).

## Read current usage

```text theme={null}
GET /api/v1/billing/usage
```

Returns usage for your organization's current billing cycle.

Included SMS/MMS and call-minute allowances, and the listed overage rates, cover U.S. and Canadian numbers. International texting and calling use international lines with pricing by country. See [Plans and pricing](https://inkbox.ai/pricing), or [contact us](https://inkbox.ai/contact) to arrange an international line.

```bash cURL theme={null}
curl "https://inkbox.ai/api/v1/billing/usage" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"
```

### Response (200)

| Field                                    | Type                     | Description                                                   |
| ---------------------------------------- | ------------------------ | ------------------------------------------------------------- |
| `cycle_start`, `cycle_end`               | integer, integer \| null | Billing-cycle boundaries in Unix seconds                      |
| `plan`                                   | string                   | Current plan                                                  |
| `channels`                               | object\[]                | Organization-wide usage by channel                            |
| `identities`                             | object\[]                | Usage and allowances by identity                              |
| `sms_allowance_per_identity`             | integer                  | Included SMS units per phone-enabled identity per cycle       |
| `voice_sec_allowance_per_identity`       | integer                  | Included call seconds per phone-enabled identity per cycle    |
| `overage_cap_cents`                      | integer \| null          | Configured SMS and voice overage limit; `null` means no limit |
| `overage_spend_cents`                    | integer                  | Estimated SMS and voice overage cost this cycle, in cents     |
| `imessage_shared_messages`               | integer                  | Shared-service iMessage messages in both directions           |
| `imessage_dedicated_messages`            | integer                  | Dedicated-line iMessage messages in both directions           |
| `imessage_unique_recipients`             | integer                  | Unique recipients using the shared iMessage service           |
| `identities_used`, `identities_included` | integer                  | Active identities and the number included in your plan        |

Each entry in `channels` contains:

| Field                | Type            | Description                                                                  |
| -------------------- | --------------- | ---------------------------------------------------------------------------- |
| `event_type`         | string          | Channel, such as `sms_outbound`                                              |
| `count`              | integer         | Message count or call seconds this cycle                                     |
| `overage`            | integer         | Units beyond the included allowance                                          |
| `est_overage_cents`  | integer \| null | Estimated overage cost; `null` when no estimate is available                 |
| `own_campaign_count` | integer \| null | SMS units carried through your own 10DLC campaign; `null` for other channels |

Each entry in `identities` contains nullable `identity_id`, `handle`, and `display_name`, plus a `channels` array of `event_type`, `count`, and `own_campaign_count`. Its nullable `sms_used`, `sms_limit`, `voice_sec_used`, and `voice_sec_limit` fields report usage and allowances. A `null` identity ID represents unattributed usage.

## Read billing settings

```text theme={null}
GET /api/v1/billing/settings
```

```bash cURL theme={null}
curl "https://inkbox.ai/api/v1/billing/settings" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"
```

### Response (200)

```json theme={null}
{
  "overage_cap_cents": null,
  "remove_branding_footer": false
}
```

## Update billing settings

```text theme={null}
PUT /api/v1/billing/settings
```

Omitted fields stay unchanged. The response returns both current settings.

| Field                    | Type            | Description                                                                                                                                 |
| ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `overage_cap_cents`      | integer \| null | SMS and voice overage limit in cents, from `0` to `10000000`. `null` removes the limit. `0` prevents new sends and calls that incur overage |
| `remove_branding_footer` | boolean \| null | `true` removes the **Sent via Inkbox** email footer on paid plans. `false` restores it. Omit or send `null` to leave it unchanged           |

This example sets a \$25 overage limit:

```bash cURL theme={null}
curl -X PUT "https://inkbox.ai/api/v1/billing/settings" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overage_cap_cents": 2500}'
```

When estimated overage spending reaches the limit, new sends and calls that would incur overage return `402` until the cycle resets or you raise the limit. Included usage remains available. Inbound and in-progress usage can exceed the limit, so this setting is not a strict invoice ceiling.

Setting `remove_branding_footer` to `true` on the Free plan returns `403`. The footer always appears on Free, even if you enabled its removal while on a paid plan.

## Related

* [Plans and pricing](https://inkbox.ai/pricing)
* [API key scopes](/docs/api-keys)
* [10DLC compliance](/docs/capabilities/phone/10dlc)