Update subscription by email OAuth Scope: subscriptions:write

PUT

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

PUT

/v2/publications/:publicationId/subscriptions/by_email/:email

$ curl -X PUT https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/subscriptions/by_email/example%40example.com \
>      -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 by email.

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

emailstringRequired

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

newsletter_list_idslist of stringsOptional

An array of newsletter list prefixed IDs to subscribe this subscription to. Adds to the subscription’s existing list memberships; it does not replace them. The newsletter lists must belong to the same publication. Cannot be combined with unsubscribe.

unsubscribe_newsletter_list_idslist of stringsOptional

An array of newsletter list prefixed IDs to unsubscribe this subscription from. Unsubscribing from a list the subscription is not on is a no-op. The newsletter lists must belong to the same publication, and the same list cannot appear in newsletter_list_ids.

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

warningslist of objectsOptional

Present when custom field data in the request could not be applied (an unknown or missing field name). The subscription is still created or updated; any unresolvable custom field values are dropped rather than the whole request failing.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error