beehiiv Developer Documentation

curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/subscriptions/sub_00000000-0000-0000-0000-000000000000 \
     -H "Authorization: Bearer <token>"

1	{
2	"data": {
3	"id": "sub_00000000-0000-0000-0000-000000000000",
4	"email": "[email protected]",
5	"status": "validating",
6	"created": 1666800076,
7	"subscription_tier": "free",
8	"subscription_premium_tier_names": [
9	"Premium",
10	"Gold"
11	],
12	"utm_source": "Twitter",
13	"utm_medium": "organic",
14	"utm_channel": "website",
15	"utm_campaign": "utm_campaign",
16	"utm_term": "",
17	"utm_content": "",
18	"referring_site": "https://www.blog.com",
19	"referral_code": "referral_code"
20	}
21	}

In previous versions of the API, another endpoint existed to retrieve a subscription by the subscriber ID. This endpoint is now deprecated and will be removed in a future version of the API. Please use this endpoint instead. The subscription ID can be found by exporting a list of subscriptions either via the Settings > Publications > Export Data or by exporting a CSV in a segment.

Retrieve a single subscription belonging to a specific publication.

<Info>In previous versions of the API, another endpoint existed to retrieve a subscription by the subscriber ID. This endpoint is now deprecated and will be removed in a future version of the API. Please use this endpoint instead. The subscription ID can be found by exporting a list of subscriptions either via the `Settings > Publications > Export Data` or by exporting a CSV in a segment.</Info> Retrieve a single subscription belonging to a specific publication.

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

subscriptionIdstringRequiredformat: "^(sub_[0-9a-fA-F\-]+)$"

The prefixed ID of the subscription 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.
tags - Returns an array of tags that have been set on the subscription.
newsletter_lists - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.

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. `tags` - Returns an array of tags 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:

Response

dataobject

The subscription object

Errors

400

Bad Request Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error