List subscriptions OAuth Scope: subscriptions:read

GET

https://api.beehiiv.com/v2/publications/:publicationId/subscriptions

GET

/v2/publications/:publicationId/subscriptions

curl -G https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/subscriptions \
     -H "Authorization: Bearer <token>" \
     -d limit=10

{
  "data": [
    {
      "id": "sub_00000000-0000-0000-0000-000000000000",
      "email": "example@example.com",
      "status": "validating",
      "created": 1666800076,
      "subscription_tier": "free",
      "subscription_premium_tier_names": [
        "Premium",
        "Gold"
      ],
      "utm_source": "Twitter",
      "utm_medium": "organic",
      "utm_channel": "website",
      "utm_campaign": "utm_campaign",
      "utm_term": "",
      "utm_content": "",
      "referring_site": "https://www.blog.com",
      "referral_code": "referral_code",
      "subscription_premium_tiers": [
        {
          "id": "tier_00000000-0000-0000-0000-000000000000",
          "name": "name",
          "status": "active"
        }
      ],
      "custom_fields": [
        {}
      ],
      "tags": [
        "Premium",
        "Basic",
        "Active",
        "Engaged"
      ],
      "stats": {
        "emails_received": 25,
        "open_rate": 60.1,
        "click_through_rate": 25
      }
    }
  ],
  "limit": 10,
  "has_more": true,
  "next_cursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ=="
}

Retrieve all subscriptions belonging to a specific publication.

New: This endpoint now supports cursor-based pagination for better performance and consistency. Use the cursor parameter instead of page for new integrations.

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 for details.

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.
subscription_premium_tiers - Returns an array of tiers the subscription is associated with.
referrals - Returns an array of subscriptions with limited data - id, email, and status. These are the subscriptions that were referred by this subscription.
stats - Returns statistics about the subscription(s).
custom_fields - Returns an array of custom field values that have been set on the subscription.
newsletter_lists - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.

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 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

datalist of objects

limitintegerOptional

The limit placed on the results. If no limit was specified in the request, this defaults to 10.

pageintegerOptional>=0Defaults to 1

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

total_pagesintegerOptional

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

has_morebooleanOptional

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

next_cursorstringOptional

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_resultsintegerOptional

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

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error