List all credit bundles

GET /api/communications/credits

Success: 200 OK

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

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.

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

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

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.

This page as markdown · All pages · llms.txt