beehiiv Developer Documentation

Update a single subscription.

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

Request

This endpoint expects an object.

tierenumOptional

Optional parameter to set the tier for this subscription.

Allowed values:

premium_tier_idslist of stringsOptional

An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with premium_tiers to include tiers from both (duplicates are removed). Takes precedence over the tier parameter.

premium_tierslist of stringsOptional

An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with premium_tier_ids to include tiers from both (duplicates are removed). Takes precedence over the tier parameter.

stripe_customer_idstringOptionalformat: "^(cus_[0-9a-zA-Z]+)?$"

The Stripe Customer ID of the subscription (not required)

unsubscribebooleanOptional

A boolean value specifying whether to unsubscribe this subscription from the publication (not required)

custom_fieldslist of objectsOptional

An array of custom field objects to update

Response

dataobject

The subscription object

1	import requests
2
3	url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/subscriptions/sub_00000000-0000-0000-0000-000000000000"
4
5	payload = {
6	"tier": "premium",
7	"stripe_customer_id": "cus_12345abcde",
8	"custom_fields": [
9	{
10	"name": "First Name",
11	"value": "Bruce"
12	},
13	{
14	"name": "Last Name",
15	"value": "Wayne"
16	}
17	]
18	}
19	headers = {
20	"Authorization": "Bearer <token>",
21	"Content-Type": "application/json"
22	}
23
24	response = requests.put(url, json=payload, headers=headers)
25
26	print(response.json())

1	{
2	"data": {
3	"id": "sub_00000000-0000-0000-0000-000000000000",
4	"email": "[email protected]",
5	"status": "active",
6	"created": 1666800076,
7	"subscription_tier": "premium",
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	"referring_site": "https://www.blog.com",
17	"referral_code": "referral_code"
18	}
19	}

Update subscription by ID

Authentication

Path parameters

Request

Response

Errors