{
  "opencollection": "1.0.0",
  "info": {
    "name": "API Reference subpackage_advertisement_opportunities subpackage_subscriptions API",
    "version": "1.0.0"
  },
  "items": [
    {
      "info": {
        "name": "subpackage_subscriptions",
        "type": "folder"
      },
      "items": [
        {
          "info": {
            "name": "List subscriptions <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "expand[]",
                "value": "",
                "type": "query",
                "description": "Optional list of expandable objects.<br>`subscription_premium_tiers ` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription. <br>`newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to."
              },
              {
                "name": "status",
                "value": "",
                "type": "query",
                "description": "Optionally filter the results by a status"
              },
              {
                "name": "tier",
                "value": "",
                "type": "query",
                "description": "Optionally filter the results by a their tier"
              },
              {
                "name": "premium_tiers[]",
                "value": "",
                "type": "query",
                "description": "Optionally filter the results by one or multiple premium tiers"
              },
              {
                "name": "premium_tier_ids[]",
                "value": "",
                "type": "query",
                "description": "Optionally filter the results by one or multiple premium tier ids"
              },
              {
                "name": "limit",
                "value": "",
                "type": "query",
                "description": "A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10."
              },
              {
                "name": "cursor",
                "value": "",
                "type": "query",
                "description": "**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. See the [Pagination Guide](/welcome/pagination) for more details."
              },
              {
                "name": "page",
                "value": "",
                "type": "query",
                "description": "**Offset-based pagination (deprecated)**: Page number for offset-based pagination. This method is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned. See the [Pagination Guide](/welcome/pagination) for migration guidance."
              },
              {
                "name": "email",
                "value": "",
                "type": "query",
                "description": "Optional email address to find a subscription.<br>This param must be an exact match and is case insensitive."
              },
              {
                "name": "order_by",
                "value": "",
                "type": "query",
                "description": "The field that the results are sorted by. Defaults to created<br> `created` - The time in which the subscription was first created.<br>"
              },
              {
                "name": "direction",
                "value": "",
                "type": "query",
                "description": "The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest."
              },
              {
                "name": "creation_date",
                "value": "",
                "type": "query",
                "description": "Optional date entry (in the format YYYY/MM/DD) that filters returned subscriptions by their creation date."
              }
            ]
          },
          "docs": "Retrieve all subscriptions belonging to a specific publication.\n\n<Info> **New**: This endpoint now supports cursor-based pagination for better performance and consistency. Use the `cursor` parameter instead of `page` for new integrations. </Info>\n<Warning> **Deprecation Notice**: Offset-based pagination (using `page` parameter) is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination. See our [Pagination Guide](/welcome/pagination) for details. </Warning>"
        },
        {
          "info": {
            "name": "Create subscription <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "POST",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              }
            ],
            "body": {
              "type": "json",
              "data": "{}"
            }
          },
          "docs": "Create new subscriptions for a publication."
        },
        {
          "info": {
            "name": "Get subscription by email <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/by_email/:email",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "email",
                "value": "",
                "type": "path",
                "description": "The ID of the subscriber object"
              },
              {
                "name": "expand[]",
                "value": "",
                "type": "query",
                "description": "Optional list of expandable objects.<br>`subscription_premium_tiers ` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription. <br>`tags` - Returns an array of tags that have been set on the subscription.<br>`newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to."
              }
            ]
          },
          "docs": "<Info>Please note that this endpoint requires the email to be URL encoded. Please reference your language's documentation for the correct method of encoding.</Info> Retrieve a single subscription belonging to a specific email address in a specific publication."
        },
        {
          "info": {
            "name": "Update subscription by email <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "PUT",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/by_email/:email",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "email",
                "value": "",
                "type": "path",
                "description": "The email of the subscription object"
              }
            ],
            "body": {
              "type": "json",
              "data": "{}"
            }
          },
          "docs": "Update a single subscription by email."
        },
        {
          "info": {
            "name": "Get subscription by ID <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/:subscriptionId",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "subscriptionId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the subscription object"
              },
              {
                "name": "expand[]",
                "value": "",
                "type": "query",
                "description": "Optional list of expandable objects.<br>`subscription_premium_tiers` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription. <br>`tags` - Returns an array of tags that have been set on the subscription.<br>`newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to."
              }
            ]
          },
          "docs": "<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."
        },
        {
          "info": {
            "name": "Update subscription by ID <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "PUT",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/:subscriptionId",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "subscriptionId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the subscription object"
              }
            ],
            "body": {
              "type": "json",
              "data": "{}"
            }
          },
          "docs": "Update a single subscription."
        },
        {
          "info": {
            "name": "Update subscription by ID <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "PATCH",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/:subscriptionId",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "subscriptionId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the subscription object"
              }
            ],
            "body": {
              "type": "json",
              "data": "{}"
            }
          },
          "docs": "Update a single subscription."
        },
        {
          "info": {
            "name": "Delete subscription <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "DELETE",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/:subscriptionId",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "subscriptionId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the subscription object"
              }
            ]
          },
          "docs": "<Warning>This cannot be undone. All data associated with the subscription will also be deleted. We recommend unsubscribing when possible instead of deleting. If a premium subscription is deleted they will no longer be billed.</Warning> Deletes a subscription."
        }
      ]
    }
  ],
  "bundled": true
}