Update subscription by ID OAuth Scope: subscriptions:write

PATCH

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

PATCH

/v2/publications/:publicationId/subscriptions/:subscriptionId

$ curl -X PATCH https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/subscriptions/sub_00000000-0000-0000-0000-000000000000 \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "email": "[email protected]",
>   "tier": "premium",
>   "stripe_customer_id": "cus_12345abcde",
>   "custom_fields": [
>     {
>       "name": "First Name",
>       "value": "Bruce"
>     },
>     {
>       "name": "Last Name",
>       "value": "Wayne"
>     }
>   ]
> }'

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     "utm_term": "",
17     "utm_content": "",
18     "referring_site": "https://www.blog.com",
19     "referral_code": "referral_code"
20   }
21 }

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.

emailstringOptional

The new email address for the subscription

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

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

The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication.

Response

dataobject

The subscription object

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error