For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
LoginStart trialGet a demo
  • Welcome
    • Getting Started
    • Create an API Key
    • Pagination
    • Rate Limiting
    • No-Code Integrations
  • Webhooks
  • OAuth2
  • API Reference
      • POSTCreate subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>
      • GETList subscriptions <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>
      • GETGet subscription by email <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>
      • GETGet subscription by ID <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>
      • PUTUpdate subscription by ID <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>
      • PATCHUpdate subscription by ID <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>
      • PUTUpdate subscription by email <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>
      • DELDelete subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>
LogoLogo
LoginStart trialGet a demo
API ReferenceSubscriptions

Update subscription by ID OAuth Scope: subscriptions:write

PUT
https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/:subscriptionId
PUT
/v2/publications/:publicationId/subscriptions/:subscriptionId
$curl -X PUT 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 '{
>  "tier": "premium",
>  "email": "[email protected]",
>  "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.
Was this page helpful?
Previous

Update subscription by ID OAuth Scope: subscriptions:write

Next
Built with

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.

emailstringOptional
The new email address for the subscription
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

OK
dataobject
The subscription object

Errors

400
Bad Request Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error