# List all credit bundles

`GET /api/communications/credits`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [List all credit bundles](https://support.gladstonesoftware.cloud/reference/communications/list-all-credit-bundles)

## Overview

Retrieves a list of email credit bundles for use with custom audiences. Includes the current available credit balance as an overview of how many credits are available to be used currently.

Credits are used in order or earliest expiring first.

If the available credits are in a negative balance, no emails to custom audiences will send. This will be shown in the bundles as an array with used credits, but no included credits.

By default only bundles that have not yet expired are returned. A tenant that has never been allocated credits gets `200` with an empty `creditBundles` array and a balance of `0`, not a `404`.

## Endpoint

`GET {base_url}/api/communications/credits`

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

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `includeExpired` | boolean | No | Whether to include bundles whose expiry date has already passed. Omitted or `false` returns only bundles expiring today or later. Setting it to `true` lengthens `creditBundles` but never changes `availableCreditBalance`, which counts unexpired bundles only. Bundles with no expiry date at all are excluded either way. |

## Sample request

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

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `availableCreditBalance` | integer (int32) | The credits spendable right now: `includedCredits` minus `usedCredits`, summed across every bundle expiring today or later. Overdrawn usage is part of that sum, so this can be negative — and while it is, emails to custom audiences are not sent. Bundles with no expiry date are not counted. |
| `creditBundles` | array of object | The tenant's credit bundles, ordered by expiry date, soonest first. Empty when the tenant has no bundles. |
| `creditBundles[].id` | integer (int32) | The bundle's identifier, unique within the tenant. It distinguishes bundles of the same type from one another. |
| `creditBundles[].typeId` | integer (int32) | How the bundle arose: `1` inclusive (credits that come with the tenant's plan), `2` one-off (credits bought separately) and `3` overdrawn (the running tally of credits used once none were left). |
| `creditBundles[].typeName` | string | The text form of `typeId` — `Inclusive`, `One-off` or `Overdrawn`. |
| `creditBundles[].includedCredits` | integer (int32) | How many credits the bundle was allocated. Always `0` on the overdrawn bundle, which records usage rather than an allocation. |
| `creditBundles[].usedCredits` | integer (int32) | How many of the bundle's credits have been consumed or reserved for a job that is still running. Credits are taken from the bundle expiring soonest first, so an older bundle fills up before a later one is touched. |
| `creditBundles[].remainingCredits` | integer (int32) | `includedCredits` minus `usedCredits`, calculated for the response rather than stored. Negative on the overdrawn bundle. |
| `creditBundles[].startDate` | string (date-time) | When the bundle takes effect. May be `null`. It plays no part in the balance calculation, which considers only the expiry date. |
| `creditBundles[].expiryDate` | string (date-time) | When the bundle expires. A bundle expiring today still counts towards `availableCreditBalance`; from tomorrow it does not, and it drops out of the default listing. The overdrawn bundle is created with `9999-12-31`, so it never expires. May be `null`, in which case the bundle is treated as expired for both purposes. |
| `creditBundles[].createdOn` | string (date-time) | When the bundle record was created. May be `null`. |

## Sample response

```json title="200 OK"
{
  "availableCreditBalance": 1,
  "creditBundles": [
    {
      "id": 12345,
      "typeId": 12345,
      "typeName": "string",
      "includedCredits": 1,
      "usedCredits": 1,
      "remainingCredits": 1,
      "startDate": "2026-08-14T19:00:00Z",
      "expiryDate": "2026-08-14T19:00:00Z",
      "createdOn": "2026-08-14T19:00:00Z"
    }
  ]
}
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `500` | Internal server error | An unexpected failure reading the tenant's credit data. The response has no body. |