beehiiv · Schema

beehiiv Subscription

Schema for a beehiiv newsletter subscription resource as returned and accepted by the beehiiv v2 REST API (https://api.beehiiv.com/v2). Represents a single subscriber to a publication.

NewsletterCreatorEmailSubscriptionPublishingMediaAdvertising

Properties

Name	Type	Description
id	string	Prefixed identifier of the subscription (e.g. sub_xxxxxxxxxxxx).
publication_id	string	Prefixed identifier of the publication this subscription belongs to (e.g. pub_xxxxxxxxxxxx).
email	string	Subscriber email address.
status	string	Subscription status.
created	integer	Unix timestamp (seconds) when the subscription was created.
subscription_tier	string	Tier of the subscription; free or a paid tier identifier.
subscription_premium_tier_names	array	Names of paid tiers the subscriber holds.
utm_source	string	UTM source captured at subscription time.
utm_medium	string	UTM medium captured at subscription time.
utm_campaign	string	UTM campaign captured at subscription time.
utm_channel	string	Channel that produced the subscription (e.g. organic, paid, referral).
referring_site	string	Referring URL captured at subscription time.
referral_code	string	Referral code used at subscription time, if any.
custom_fields	array	Custom field name/value pairs attached to this subscriber.
tags	array	Subscriber tags.
stats	object	Engagement statistics for the subscriber.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.com/schemas/beehiiv/beehiiv-subscription-schema.json",
  "title": "beehiiv Subscription",
  "description": "Schema for a beehiiv newsletter subscription resource as returned and accepted by the beehiiv v2 REST API (https://api.beehiiv.com/v2). Represents a single subscriber to a publication.",
  "type": "object",
  "required": ["id", "email", "status", "publication_id"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Prefixed identifier of the subscription (e.g. sub_xxxxxxxxxxxx)."
    },
    "publication_id": {
      "type": "string",
      "description": "Prefixed identifier of the publication this subscription belongs to (e.g. pub_xxxxxxxxxxxx)."
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Subscriber email address."
    },
    "status": {
      "type": "string",
      "description": "Subscription status.",
      "enum": ["active", "validating", "invalid", "pending", "inactive", "needs_attention"]
    },
    "created": {
      "type": "integer",
      "description": "Unix timestamp (seconds) when the subscription was created."
    },
    "subscription_tier": {
      "type": "string",
      "description": "Tier of the subscription; free or a paid tier identifier.",
      "enum": ["free", "premium"]
    },
    "subscription_premium_tier_names": {
      "type": "array",
      "description": "Names of paid tiers the subscriber holds.",
      "items": { "type": "string" }
    },
    "utm_source": { "type": "string", "description": "UTM source captured at subscription time." },
    "utm_medium": { "type": "string", "description": "UTM medium captured at subscription time." },
    "utm_campaign": { "type": "string", "description": "UTM campaign captured at subscription time." },
    "utm_channel": { "type": "string", "description": "Channel that produced the subscription (e.g. organic, paid, referral)." },
    "referring_site": { "type": "string", "description": "Referring URL captured at subscription time." },
    "referral_code": { "type": "string", "description": "Referral code used at subscription time, if any." },
    "custom_fields": {
      "type": "array",
      "description": "Custom field name/value pairs attached to this subscriber.",
      "items": {
        "type": "object",
        "required": ["name", "value"],
        "properties": {
          "name": { "type": "string", "description": "Custom field name." },
          "value": { "description": "Custom field value (string, number, boolean, or date)." }
        }
      }
    },
    "tags": {
      "type": "array",
      "description": "Subscriber tags.",
      "items": { "type": "string" }
    },
    "stats": {
      "type": "object",
      "description": "Engagement statistics for the subscriber.",
      "properties": {
        "open_rate": { "type": "number", "description": "Lifetime email open rate (0-1)." },
        "click_rate": { "type": "number", "description": "Lifetime click-through rate (0-1)." }
      }
    }
  }
}