API ReferenceSubscriptions

List subscriptions

Retrieve all subscriptions belonging to a specific publication. <Info> **New**: This endpoint now supports cursor-based pagination for better performance and consistency. Use the `cursor` parameter instead of `page` for new integrations. </Info> <Warning> **Deprecation Notice**: Offset-based pagination (using `page` parameter) is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination. See our [Pagination Guide](/welcome/pagination) for details. </Warning>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"
The prefixed ID of the publication object

Query parameters

expand[]enumOptional
Optional list of expandable objects.<br>`subscription_premium_tiers ` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription.
Allowed values:
statusenumOptionalDefaults to all
Optionally filter the results by a status
tierenumOptionalDefaults to all
Optionally filter the results by a their tier
Allowed values:
premium_tiers[]stringOptional
Optionally filter the results by one or multiple premium tiers
premium_tier_ids[]stringOptional
Optionally filter the results by one or multiple premium tier ids
limitintegerOptional
A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
cursorstringOptional

Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. See the Pagination Guide for more details.

pageintegerOptional
**Offset-based pagination (deprecated)**: Page number for offset-based pagination. This method is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned. See the [Pagination Guide](/welcome/pagination) for migration guidance.
emailstringOptional

Optional email address to find a subscription.
This param must be an exact match and is case insensitive.

order_byenumOptionalDefaults to created

The field that the results are sorted by. Defaults to created
created - The time in which the subscription was first created.

Allowed values:
directionenumOptionalDefaults to asc

The direction that the results are sorted in. Defaults to asc
asc - Ascending, sorts from smallest to largest.
desc - Descending, sorts from largest to smallest.

Allowed values:
creation_datestringOptional

Optional date entry (in the format YYYY/MM/DD) that filters returned subscriptions by their creation date.

Response

OK
datalist of objects
limitinteger or null
The limit placed on the results. If no limit was specified in the request, this defaults to 10.
pageinteger or null>=0Defaults to 1

Offset pagination only: The page number the results are from. Only present when using deprecated offset-based pagination.

total_pagesinteger or null

Offset pagination only: The total number of pages. Only present when using deprecated offset-based pagination.

has_moreboolean or null

Cursor pagination only: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination.

next_cursorstring or null

Cursor pagination only: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination.

total_resultsinteger or null

Mixed pagination: The total number of results from all pages. For offset-based pagination, this is always included.

Errors