# Retrieves all communication credit plans for a specific environment

`GET /api/configuration/communication-plans/{environmentId}`

- **Success:** `200 OK`
- **Products:** Gladstone Admin Areas (`ADMIN`)
- **Features:** not restricted by feature

HTML version: [Retrieves all communication credit plans for a specific environment](https://support.gladstonesoftware.cloud/reference/configuration/retrieves-all-communication-credit-plans-for-a-specific-environment)

## Overview

Lists the communication credit allocations held by one environment — the bundles of emails and SMS
messages that environment may send. Use it to show what has been allocated and when it runs out.

Two kinds of record appear here: allocations taken from a standard plan, which carry that plan's
name and limits, and one-off bundles bought outright, which have no plan behind them and therefore
come back with a null `planName`, `audienceLimit` and `siteLimit`. Check `planName` rather than
assuming every entry describes a plan.

**These are allocations, not balances.** `includedEmails` and `includedSMS` are what the environment
was given, not what it has left — nothing in this response tells you how much has been used.

By default only active allocations are returned; pass `includeInactive=true` to see expired and
switched-off ones too. Results are ordered newest first by `startDate`, and an environment with no
allocations returns `200` with an empty array. An environment id that does not exist is a `400`, not
an empty list.

The standard plans an allocation can be based on are listed by
[Retrieve all default communication credit plans](retrieves-all-default-communication-credit-plans-available-in-the-system.md).

## Endpoint

`GET {base_url}/api/configuration/communication-plans/{environmentId}`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `environmentId` | integer (int32) | Yes | The environment whose allocations you want. It is checked before anything is read: an id that does not exist fails with `400` and `EnvironmentId {environmentId} does not exist.` |

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `includeInactive` | boolean | No | Whether to include allocations that are switched off or have expired. **Defaults to `false`**, so by default you see only allocations flagged active. Set it to `true` for a history. It filters on the stored active flag alone, so an allocation whose `expiryDate` has passed but which has not been deactivated is still returned either way — compare `expiryDate` yourself. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/configuration/communication-plans/{environmentId}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | integer (int32) | Identifies this allocation to this environment, not the underlying plan. This is the id used when the allocation is updated. Do not confuse it with `planId`. |
| `[].planId` | integer (int32) | The standard plan this allocation was created from, matching `id` in [Retrieve all default communication credit plans](retrieves-all-default-communication-credit-plans-available-in-the-system.md). A one-off bundle bought outside any plan has no plan behind it, and its plan-derived fields come back null. |
| `[].planName` | string | The name of the standard plan behind this allocation, copied from the plan record. `null` for a one-off bundle — this is the most reliable way to tell the two kinds apart. |
| `[].audienceLimit` | integer (int32) | The plan's cap on audience size, taken from the plan rather than from the allocation. `null` for a one-off bundle, and also `null` on a plan that sets no cap. |
| `[].siteLimit` | integer (int32) | The plan's cap on the number of sites it covers, taken from the plan. `null` for a one-off bundle, and also `null` on a plan that sets no cap. |
| `[].isActive` | boolean | Whether the allocation is switched on. Always `true` unless you asked for `includeInactive`. It is a stored flag, independent of `expiryDate`, so an active allocation can still be past its expiry. |
| `[].startDate` | string (date-time) | When the allocation begins. It is the sort key — results come back newest first — so the first entry is the most recently started allocation, which is usually but not necessarily the current one. |
| `[].expiryDate` | string (date-time) | When the allocation runs out. `null` where no expiry was set, which means it does not lapse on a date. Expiry does not clear `isActive` by itself, so check both before telling a user their credits are still available. |
| `[].includedEmails` | integer (int32) | How many emails this allocation granted. It is the amount allocated, not the amount remaining, and it is held on the allocation rather than read from the plan — so it can differ from the plan's headline figure. `0` where none were recorded. |
| `[].includedSMS` | integer (int32) | How many SMS messages this allocation granted, on the same terms as `includedEmails`: allocated rather than remaining, held on the allocation, and `0` where none were recorded. Note the upper-case `SMS` in the field name. |

## Sample response

```json title="200 OK"
[
  {
    "id": 12345,
    "planId": 12345,
    "planName": "string",
    "audienceLimit": 1,
    "siteLimit": 1,
    "isActive": true,
    "startDate": "2026-08-14T19:00:00Z",
    "expiryDate": "2026-08-14T19:00:00Z",
    "includedEmails": 1,
    "includedSMS": 1
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | No environment exists with the id you supplied. The body is the plain string `EnvironmentId {environmentId} does not exist.` An environment that exists but has no allocations returns `200` with an empty array instead. |
| `500` | Internal server error | An unexpected server-side failure while reading the allocations, with an empty body. |