Skip to content

reference.md

Latest commit

 

History

History
4611 lines (3238 loc) · 65.5 KB

reference.md

File metadata and controls

4611 lines (3238 loc) · 65.5 KB

Reference

Automation Journeys

client.automationJourneys.create(publicationId, automationId, { ...params }) -> Beehiiv.AutomationJourneysResponse

📝 Description

Add an existing subscription to an automation flow. Requires the automation to have an active Add by API trigger. The specified email or subscription_id will be matched against your existing subscribers. If an existing subscriber is found, they will be enrolled immediately.

Looking to enroll new subscribers? Use the Create Subscription endpoint instead and specify the automation_ids param.

🔌 Usage

await client.automationJourneys.create("pub_00000000-0000-0000-0000-000000000000", "aut_00000000-0000-0000-0000-000000000000", {
    email: "test@example.com",
    double_opt_override: "on"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

automationId: Beehiiv.AutomationId — The prefixed ID of the automation object

request: Beehiiv.AutomationJourneysCreateRequest

requestOptions: AutomationJourneysClient.RequestOptions

client.automationJourneys.index(publicationId, automationId, { ...params }) -> Beehiiv.AutomationJourneysIndexResponse

📝 Description

Retrieve a list of automation journeys that have occurred within a specific automation.

🔌 Usage

await client.automationJourneys.index("pub_00000000-0000-0000-0000-000000000000", "aut_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

automationId: Beehiiv.AutomationId — The prefixed ID of the automation object

request: Beehiiv.AutomationJourneysIndexRequest

requestOptions: AutomationJourneysClient.RequestOptions

client.automationJourneys.show(publicationId, automationId, automationJourneyId) -> Beehiiv.AutomationJourneysResponse

📝 Description

Retrieve a single automation journey by ID.

🔌 Usage

await client.automationJourneys.show("pub_00000000-0000-0000-0000-000000000000", "aut_00000000-0000-0000-0000-000000000000", "aj_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

automationId: Beehiiv.AutomationId — The prefixed ID of the automation object

automationJourneyId: Beehiiv.AutomationJourneyId — The prefixed automation journey id

requestOptions: AutomationJourneysClient.RequestOptions

Automations

client.automations.index(publicationId, { ...params }) -> Beehiiv.AutomationsListResponse

🔌 Usage

await client.automations.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.AutomationsListRequest

requestOptions: AutomationsClient.RequestOptions

client.automations.show(publicationId, automationId) -> Beehiiv.AutomationsGetResponse

🔌 Usage

await client.automations.show("pub_00000000-0000-0000-0000-000000000000", "aut_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

automationId: Beehiiv.AutomationId — The prefixed ID of the automation object

requestOptions: AutomationsClient.RequestOptions

Bulk Subscriptions

client.bulkSubscriptions.create(publicationId, { ...params }) -> Beehiiv.BulkSubscriptionCreateResponse

📝 Description

Create new subscriptions for a publication.

🔌 Usage

await client.bulkSubscriptions.create("pub_00000000-0000-0000-0000-000000000000", {
    subscriptions: [{
            email: "bruce.wayne@wayneenterprise.com",
            reactivate_existing: false,
            send_welcome_email: false,
            custom_fields: [{
                    name: "Favorite Color",
                    value: "Red"
                }]
        }, {
            email: "lucius.fox@wayneenterprise.com",
            reactivate_existing: false,
            send_welcome_email: false,
            custom_fields: [{
                    name: "Favorite Color",
                    value: "Blue"
                }]
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.BulkSubscriptionsCreateRequest

requestOptions: BulkSubscriptionsClient.RequestOptions

Bulk Subscription Updates

client.bulkSubscriptionUpdates.index(publicationId) -> Beehiiv.BulkSubscriptionUpdatesListResponse

📝 Description

Returns a list of Subscription Update objects for a publication.

🔌 Usage

await client.bulkSubscriptionUpdates.index("publicationId");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

requestOptions: BulkSubscriptionUpdatesClient.RequestOptions

client.bulkSubscriptionUpdates.show(publicationId, id) -> Beehiiv.BulkSubscriptionUpdatesGetResponse

📝 Description

Returns a single Subscription Update object for a publication.

🔌 Usage

await client.bulkSubscriptionUpdates.show("publicationId", "id");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

id: string — The ID of the Subscription Update object

requestOptions: BulkSubscriptionUpdatesClient.RequestOptions

client.bulkSubscriptionUpdates.put(publicationId, { ...params }) -> Beehiiv.SubscriptionsPatchResponse

📝 Description

Bulk update multiple subscriptions fields, including status, custom fields, and tiers.

🔌 Usage

await client.bulkSubscriptionUpdates.put("publicationId", {
    subscriptions: [{
            subscription_id: "sub_1234-5678-9012-3456-7890",
            tier: "premium",
            stripe_customer_id: "cus_1234567890",
            unsubscribe: false,
            custom_fields: [{
                    name: "custom_field_name",
                    value: "custom_field_value"
                }, {
                    name: "custom_field_name_2",
                    value: "custom_field_value_2"
                }]
        }, {
            subscription_id: "sub_9876-5432-1098-7654-3210",
            tier: "free",
            stripe_customer_id: "cus_1234567890",
            unsubscribe: true,
            custom_fields: [{
                    name: "custom_field_name_3",
                    value: "custom_field_value_3"
                }, {
                    name: "custom_field_name_4",
                    value: "custom_field_value_4"
                }]
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.BulkSubscriptionsPutRequest

requestOptions: BulkSubscriptionUpdatesClient.RequestOptions

client.bulkSubscriptionUpdates.patch(publicationId, { ...params }) -> Beehiiv.SubscriptionsPatchResponse

📝 Description

Bulk update multiple subscriptions fields, including status, custom fields, and tiers.

🔌 Usage

await client.bulkSubscriptionUpdates.patch("publicationId", {
    subscriptions: [{
            subscription_id: "sub_1234-5678-9012-3456-7890",
            tier: "premium",
            stripe_customer_id: "cus_1234567890",
            unsubscribe: false,
            custom_fields: [{
                    name: "custom_field_name",
                    value: "custom_field_value"
                }, {
                    name: "custom_field_name_2",
                    value: "custom_field_value_2"
                }]
        }, {
            subscription_id: "sub_9876-5432-1098-7654-3210",
            tier: "free",
            stripe_customer_id: "cus_1234567890",
            unsubscribe: true,
            custom_fields: [{
                    name: "custom_field_name_3",
                    value: "custom_field_value_3"
                }, {
                    name: "custom_field_name_4",
                    value: "custom_field_value_4"
                }]
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.BulkSubscriptionsPatchRequest

requestOptions: BulkSubscriptionUpdatesClient.RequestOptions

client.bulkSubscriptionUpdates.putStatus(publicationId, { ...params }) -> void

📝 Description

Bulk update subscriptions' status.

🔌 Usage

await client.bulkSubscriptionUpdates.putStatus("publicationId", {
    subscription_ids: ["sub_1234-5678-9012-3456-7890", "sub_9876-5432-1098-7654-3210"],
    new_status: "active"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.BulkSubscriptionsStatusPutRequest

requestOptions: BulkSubscriptionUpdatesClient.RequestOptions

client.bulkSubscriptionUpdates.patchStatus(publicationId, { ...params }) -> void

📝 Description

Bulk update subscriptions' status.

🔌 Usage

await client.bulkSubscriptionUpdates.patchStatus("publicationId", {
    subscription_ids: ["sub_1234-5678-9012-3456-7890", "sub_9876-5432-1098-7654-3210"],
    new_status: "active"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.BulkSubscriptionsStatusPatchRequest

requestOptions: BulkSubscriptionUpdatesClient.RequestOptions

Custom Fields

client.customFields.create(publicationId, { ...params }) -> Beehiiv.CustomFieldResponse

📝 Description

Create a custom field on a publication, for use in subscriptions

🔌 Usage

await client.customFields.create("publicationId", {
    kind: "string",
    display: "Display"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.CustomFieldsCreateRequest

requestOptions: CustomFieldsClient.RequestOptions

client.customFields.show(publicationId, id) -> Beehiiv.CustomFieldResponse

📝 Description

View a specific custom field on a publication

🔌 Usage

await client.customFields.show("publicationId", "id");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

id: string — The ID of the Custom Fields object

requestOptions: CustomFieldsClient.RequestOptions

client.customFields.index(publicationId) -> Beehiiv.CustomFieldIndexResponse

📝 Description

List all custom fields on a publication

🔌 Usage

await client.customFields.index("publicationId");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

requestOptions: CustomFieldsClient.RequestOptions

client.customFields.put(publicationId, id, { ...params }) -> Beehiiv.CustomFieldResponse

📝 Description

Update a custom field on a publication

🔌 Usage

await client.customFields.put("publicationId", "id", {
    display: "New Display"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

id: string — The ID of the Custom Fields object

request: Beehiiv.CustomFieldsPutRequest

requestOptions: CustomFieldsClient.RequestOptions

client.customFields.patch(publicationId, id, { ...params }) -> Beehiiv.CustomFieldsPatchResponse

📝 Description

Update a custom field on a publication

🔌 Usage

await client.customFields.patch("publicationId", "id", {
    display: "New Display"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

id: string — The ID of the Custom Fields object

request: Beehiiv.CustomFieldsPatchRequest

requestOptions: CustomFieldsClient.RequestOptions

client.customFields.delete(publicationId, id) -> Beehiiv.CustomFieldsDeleteResponse

📝 Description

Delete a custom field from a publication

🔌 Usage

await client.customFields.delete("publicationId", "id");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

id: string — The ID of the Custom Fields object

requestOptions: CustomFieldsClient.RequestOptions

Email Blasts

client.emailBlasts.index(publicationId, { ...params }) -> Beehiiv.EmailBlastsListResponse

📝 Description

Retrieve all email blasts belonging to a specific publication

🔌 Usage

await client.emailBlasts.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.EmailBlastsListRequest

requestOptions: EmailBlastsClient.RequestOptions

client.emailBlasts.show(publicationId, emailBlastId, { ...params }) -> Beehiiv.EmailBlastsGetResponse

📝 Description

Retrieve a single email blast belonging to a specific publication

🔌 Usage

await client.emailBlasts.show("pub_00000000-0000-0000-0000-000000000000", "blast_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

emailBlastId: Beehiiv.EmailBlastId — The prefixed ID of the email blast object

request: Beehiiv.EmailBlastsGetRequest

requestOptions: EmailBlastsClient.RequestOptions

Posts

client.posts.create(publicationId, { ...params }) -> Beehiiv.PostsCreateResponse

📝 Description

This feature is currently in beta, the API is subject to change, and available only to Enterprise users.

To inquire about Enterprise pricing, please visit our Enterprise page. Create a post for a specific publication.

🔌 Usage

await client.posts.create("pub_00000000-0000-0000-0000-000000000000", {
    title: "The Kitchen Sink Post (refactored version)",
    subtitle: "Contains lots of examples of each block type and the various settings you could use",
    blocks: [{
            type: "heading",
            level: "2",
            textAlignment: "center",
            text: "This is my block!!!",
            anchorHeader: false,
            anchorIncludeInToc: false
        }, {
            type: "list",
            listType: "ordered",
            items: ["a", "b", "c"]
        }, {
            type: "list",
            listType: "ordered",
            items: ["d", "e", "f"],
            startNumber: 4
        }, {
            type: "list",
            listType: "unordered",
            items: ["g", "h", "i"],
            startNumber: 4
        }, {
            type: "table",
            headerRow: true,
            headerColumn: true,
            rows: [[{
                        text: "A"
                    }, {
                        text: "B",
                        alignment: "center"
                    }, {
                        text: "C",
                        alignment: "right"
                    }], [{
                        text: "D",
                        alignment: "right"
                    }, {
                        text: "E",
                        alignment: "center"
                    }, {
                        text: "F",
                        alignment: "left"
                    }]]
        }, {
            type: "table",
            rows: [[{
                        text: "A"
                    }, {
                        text: "B"
                    }, {
                        text: "C"
                    }], [{
                        text: "D"
                    }, {
                        text: "E"
                    }, {
                        text: "F"
                    }]]
        }, {
            type: "table",
            headerRow: false,
            rows: [[{
                        text: "A"
                    }, {
                        text: "B"
                    }, {
                        text: "C"
                    }], [{
                        text: "D"
                    }, {
                        text: "E"
                    }, {
                        text: "F"
                    }]]
        }, {
            type: "columns",
            columns: [{
                    blocks: [{
                            type: "paragraph",
                            plaintext: "Marble Column 1 {{email}}"
                        }]
                }, {
                    blocks: [{
                            type: "image",
                            imageUrl: "https://cdn.britannica.com/89/164789-050-D6B5E2C7/Barack-Obama-2012.jpg",
                            url: "https://www.whitehouse.gov/",
                            title: "Barry O",
                            alt_text: "A picture of Barry Obama",
                            caption: "One Cool President",
                            captionAlignment: "center",
                            imageAlignment: "right",
                            width: 75
                        }]
                }]
        }, {
            type: "advertisement",
            opportunity_id: "d8dfa6be-24b5-4cad-8350-ae44366dbd4c"
        }, {
            type: "image",
            imageUrl: "https://cdn.britannica.com/89/164789-050-D6B5E2C7/Barack-Obama-2012.jpg",
            url: "https://www.whitehouse.gov/",
            title: "Barry O",
            alt_text: "A picture of Barry Obama",
            caption: "One Cool President",
            captionAlignment: "center",
            imageAlignment: "right",
            width: 75
        }, {
            type: "paragraph",
            formattedText: [{
                    text: "This is going to be "
                }, {
                    text: "a really, really awesome time ",
                    styling: ["bold"]
                }, {
                    text: "Are you ready for this?",
                    styling: ["italic", "bold"]
                }]
        }, {
            type: "button",
            href: "/subscribe",
            target: "_blank",
            alignment: "center",
            size: "large",
            text: "Subscribe"
        }, {
            type: "button",
            href: "/signup",
            target: "_blank",
            alignment: "right",
            size: "small",
            text: "Sign Up"
        }, {
            type: "button",
            href: "/",
            target: "_blank",
            text: "View Posts"
        }, {
            type: "heading",
            level: "4",
            textAlignment: "right",
            text: "This is my block!!!",
            anchorHeader: true,
            anchorIncludeInToc: true
        }],
    post_template_id: "post_template_00000000-0000-0000-0000-000000000000",
    scheduled_at: "2024-12-25T12:00:00Z",
    custom_link_tracking_enabled: true,
    email_capture_type_override: "none",
    override_scheduled_at: "2022-10-26T14:01:16Z",
    social_share: "comments_and_likes_only",
    thumbnail_image_url: "https://images.squarespace-cdn.com/content/v1/56e4ca0540261d39b90e4b18/1605047208324-PONGEYKEAKTMM1LANHJ5/1ED706BF-A70B-4F26-B3D5-266B449DDA8A_1_105_c.jpeg",
    email_settings: {
        from_address: "from_address",
        custom_live_url: "https://beehiiv.com",
        display_title_in_email: true,
        display_byline_in_email: true,
        display_subtitle_in_email: true,
        email_header_engagement_buttons: "email_header_engagement_buttons",
        email_header_social_share: "email_header_social_share",
        email_preview_text: "email_preview_text",
        email_subject_line: "email_subject_line"
    },
    web_settings: {
        display_thumbnail_on_web: true,
        hide_from_feed: true,
        slug: "and-this-is-gonna-rock"
    },
    seo_settings: {
        default_description: "default_description",
        default_title: "default_title",
        og_description: "OpenGraph description",
        og_title: "Opengraph Title",
        twitter_description: "Twitter Stuff",
        twitter_title: "My Twitter Article"
    },
    content_tags: ["Obama", "Care", "Rocks", "Healthcare"],
    recipients: {
        web: {
            tier_ids: ["premium"]
        },
        email: {
            tier_ids: ["premium", "free"],
            include_segment_ids: ["seg_6426b403-39f5-42bd-86e9-9533fb0099e7"],
            exclude_segment_ids: ["seg_e34b4085-aef6-449f-a699-7563f915f852"]
        }
    }
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PostsCreateRequest

requestOptions: PostsClient.RequestOptions

client.posts.index(publicationId, { ...params }) -> Beehiiv.PostsListResponse

📝 Description

Retrieve all posts belonging to a specific publication

🔌 Usage

await client.posts.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PostsListRequest

requestOptions: PostsClient.RequestOptions

client.posts.aggregateStats(publicationId, { ...params }) -> Beehiiv.PostsAggregateStatsResponse

📝 Description

Retrieve aggregate stats for all posts

🔌 Usage

await client.posts.aggregateStats("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PostsAggregateStatsRequest

requestOptions: PostsClient.RequestOptions

client.posts.show(publicationId, postId, { ...params }) -> Beehiiv.PostsGetResponse

📝 Description

Retreive a single Post belonging to a specific publication

🔌 Usage

await client.posts.show("pub_00000000-0000-0000-0000-000000000000", "post_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

postId: Beehiiv.PostId — The prefixed ID of the post object

request: Beehiiv.PostsGetRequest

requestOptions: PostsClient.RequestOptions

client.posts.delete(publicationId, postId) -> Beehiiv.PostsDeleteResponse

📝 Description

Delete or Archive a post. Any post that has been confirmed will have it's status changed to archived. Posts in the draft status will be permanently deleted.

🔌 Usage

await client.posts.delete("pub_00000000-0000-0000-0000-000000000000", "post_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

postId: Beehiiv.PostId — The prefixed ID of the post object

requestOptions: PostsClient.RequestOptions

Post Templates

client.postTemplates.index(publicationId, { ...params }) -> Beehiiv.PostTemplatesGetResponse

📝 Description

Retrieve a list of post templates available for the publication.

🔌 Usage

await client.postTemplates.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PostTemplatesGetRequest

requestOptions: PostTemplatesClient.RequestOptions

Publications

client.publications.index({ ...params }) -> Beehiiv.PublicationsListResponse

📝 Description

Retrieve all publications associated with your API key.

🔌 Usage

await client.publications.index();

⚙️ Parameters

request: Beehiiv.PublicationsListRequest

requestOptions: PublicationsClient.RequestOptions

client.publications.show(publicationId, { ...params }) -> Beehiiv.PublicationsGetResponse

📝 Description

Retrieve a single publication

🔌 Usage

await client.publications.show("pub_ad76629e-4a39-43ad-8055-0ee89dc6db15");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PublicationsGetRequest

requestOptions: PublicationsClient.RequestOptions

Referral Program

client.referralProgram.show(publicationId, { ...params }) -> Beehiiv.ReferralProgramGetResponse

📝 Description

Retrieve details about the publication's referral program, including milestones and rewards.

🔌 Usage

await client.referralProgram.show("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.ReferralProgramGetRequest

requestOptions: ReferralProgramClient.RequestOptions

Segments

client.segments.index(publicationId, { ...params }) -> Beehiiv.SegmentsListResponse

📝 Description

Retrieve information about all segments belonging to a specific publication

🔌 Usage

await client.segments.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.SegmentsListRequest

requestOptions: SegmentsClient.RequestOptions

client.segments.show(publicationId, segmentId, { ...params }) -> Beehiiv.SegmentShowResponse

📝 Description

Retrieve information about a specific segment belonging to a publication

🔌 Usage

await client.segments.show("pub_00000000-0000-0000-0000-000000000000", "seg_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

segmentId: Beehiiv.SegmentId — The prefixed ID of the segment object

request: Beehiiv.SegmentsShowRequest

requestOptions: SegmentsClient.RequestOptions

client.segments.recalculate(publicationId, segmentId) -> Beehiiv.SegmentRecalculateResponse

📝 Description

Recalculates a specific segment belonging to a publication

🔌 Usage

await client.segments.recalculate("pub_00000000-0000-0000-0000-000000000000", "seg_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

segmentId: Beehiiv.SegmentId — The prefixed ID of the segment object

requestOptions: SegmentsClient.RequestOptions

client.segments.listMembers(publicationId, segmentId, { ...params }) -> Beehiiv.SegmentMembersResponse

📝 Description

List all members in a segment with full subscription data. Each member is returned as a subscription object containing complete subscriber information and their subscription details. Supports optional expansions for stats, custom fields, tags, referrals, and premium tiers.

Use this endpoint when you need detailed subscriber information. If you only need subscriber IDs, use /segments/{segmentId}/results for a lighter-weight response.

🔌 Usage

await client.segments.listMembers("pub_00000000-0000-0000-0000-000000000000", "seg_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

segmentId: Beehiiv.SegmentId — The prefixed ID of the segment object

request: Beehiiv.SegmentMembersRequest

requestOptions: SegmentsClient.RequestOptions

client.segments.expandResults(publicationId, segmentId, { ...params }) -> Beehiiv.SegmentsGetResponse

📝 Description

List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details.

Use this endpoint when you only need subscriber IDs (e.g., for counting, ID-based lookups, or integrations with external systems). If you need full subscriber details (email, status, custom fields, etc.), use /segments/{segmentId}/members instead.

🔌 Usage

await client.segments.expandResults("pub_00000000-0000-0000-0000-000000000000", "seg_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

segmentId: Beehiiv.SegmentId — The prefixed ID of the segment object

request: Beehiiv.SegmentsGetRequest

requestOptions: SegmentsClient.RequestOptions

client.segments.delete(publicationId, segmentId) -> Beehiiv.SegmentDeleteResponse

📝 Description

Delete a segment. Deleting the segment does not effect the subscriptions in the segment.

🔌 Usage

await client.segments.delete("pub_00000000-0000-0000-0000-000000000000", "seg_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

segmentId: Beehiiv.SegmentId — The prefixed ID of the segment object

requestOptions: SegmentsClient.RequestOptions

Subscriptions

client.subscriptions.create(publicationId, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

Create new subscriptions for a publication.

🔌 Usage

await client.subscriptions.create("pub_00000000-0000-0000-0000-000000000000", {
    email: "bruce.wayne@wayneenterprise.com",
    reactivate_existing: false,
    send_welcome_email: false,
    utm_source: "WayneEnterprise",
    utm_medium: "organic",
    utm_campaign: "fall_2022_promotion",
    referring_site: "www.wayneenterprise.com/blog",
    custom_fields: [{
            name: "First Name",
            value: "Bruce"
        }, {
            name: "Last Name",
            value: "Wayne"
        }],
    stripe_customer_id: "cus_12345abcde"
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.SubscriptionRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.index(publicationId, { ...params }) -> Beehiiv.SubscriptionsListResponse

📝 Description

Retrieve all subscriptions belonging to a specific publication. New: This endpoint now supports cursor-based pagination for better performance and consistency. Use the cursor parameter instead of page for new integrations. 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 for details.

🔌 Usage

await client.subscriptions.index("pub_00000000-0000-0000-0000-000000000000", {
    limit: 10
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.SubscriptionsListRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.getByEmail(publicationId, email, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

Please note that this endpoint requires the email to be URL encoded. Please reference your language's documentation for the correct method of encoding. Retrieve a single subscription belonging to a specific email address in a specific publication.

🔌 Usage

await client.subscriptions.getByEmail("pub_00000000-0000-0000-0000-000000000000", "work@example.com");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

email: string — The ID of the subscriber object

request: Beehiiv.SubscriptionsGetRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.getById(publicationId, subscriptionId, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

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. Retrieve a single subscription belonging to a specific publication.

🔌 Usage

await client.subscriptions.getById("pub_00000000-0000-0000-0000-000000000000", "sub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

subscriptionId: Beehiiv.SubscriptionId — The prefixed ID of the subscription object

request: Beehiiv.SubscriptionsGetByIdRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.getBySubscriberId(publicationId, subscriberId, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

Retrieve a single subscription belonging to a specific publication via the subscriber ID.

🔌 Usage

await client.subscriptions.getBySubscriberId("pub_00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

subscriberId: string — The ID of the subscriber object

request: Beehiiv.SubscriptionsGetBySubscriberIdRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.getJwtToken(publicationId, subscriptionId) -> Beehiiv.SubscriptionJwtTokenResponse

📝 Description

Generate a JWT token that can be used to automatically log in subscribers via URL. This token is short lived and should be used immediately.

🔌 Usage

await client.subscriptions.getJwtToken("pub_00000000-0000-0000-0000-000000000000", "sub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

subscriptionId: Beehiiv.SubscriptionId — The prefixed ID of the subscription object

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.put(publicationId, subscriptionId, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

Update a single subscription.

🔌 Usage

await client.subscriptions.put("pub_00000000-0000-0000-0000-000000000000", "sub_00000000-0000-0000-0000-000000000000", {
    tier: "premium",
    stripe_customer_id: "cus_12345abcde",
    custom_fields: [{
            name: "First Name",
            value: "Bruce"
        }, {
            name: "Last Name",
            value: "Wayne"
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

subscriptionId: Beehiiv.SubscriptionId — The prefixed ID of the subscription object

request: Beehiiv.SubscriptionsUpdateRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.patch(publicationId, subscriptionId, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

Update a single subscription.

🔌 Usage

await client.subscriptions.patch("pub_00000000-0000-0000-0000-000000000000", "sub_00000000-0000-0000-0000-000000000000", {
    tier: "premium",
    stripe_customer_id: "cus_12345abcde",
    custom_fields: [{
            name: "First Name",
            value: "Bruce"
        }, {
            name: "Last Name",
            value: "Wayne"
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

subscriptionId: Beehiiv.SubscriptionId — The prefixed ID of the subscription object

request: Beehiiv.SubscriptionsPatchSingleRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.updateByEmail(publicationId, email, { ...params }) -> Beehiiv.SubscriptionResponse

📝 Description

Update a single subscription by email.

🔌 Usage

await client.subscriptions.updateByEmail("pub_00000000-0000-0000-0000-000000000000", "example@example.com", {
    tier: "premium",
    stripe_customer_id: "cus_12345abcde",
    custom_fields: [{
            name: "First Name",
            value: "Bruce"
        }, {
            name: "Last Name",
            value: "Wayne"
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

email: string — The email of the subscription object

request: Beehiiv.SubscriptionsUpdateByEmailRequest

requestOptions: SubscriptionsClient.RequestOptions

client.subscriptions.delete(publicationId, subscriptionId) -> Beehiiv.SubscriptionDeleteResponse

📝 Description

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. Deletes a subscription.

🔌 Usage

await client.subscriptions.delete("pub_00000000-0000-0000-0000-000000000000", "sub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

subscriptionId: Beehiiv.SubscriptionId — The prefixed ID of the subscription object

requestOptions: SubscriptionsClient.RequestOptions

Subscription Tags

client.subscriptionTags.create(publicationId, subscriptionId, { ...params }) -> Beehiiv.SubscriptionTagsCreateResponse

📝 Description

Adds tags to a subscription. If the tag does not exist on the publication, it will be created automatically.

🔌 Usage

await client.subscriptionTags.create("publicationId", "subscriptionId", {
    tags: ["Premium", "Basic"]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId

subscriptionId: Beehiiv.SubscriptionId

request: Beehiiv.SubscriptionTagsCreateRequest

requestOptions: SubscriptionTagsClient.RequestOptions

Tiers

client.tiers.create(publicationId, { ...params }) -> Beehiiv.TierResponse

📝 Description

Create a new tier for a publication.

🔌 Usage

await client.tiers.create("pub_00000000-0000-0000-0000-000000000000", {
    name: "Gold Tier",
    description: "Our premium tier with exclusive benefits",
    prices_attributes: [{
            currency: "usd",
            amount_cents: 500,
            enabled: true,
            interval: "month",
            interval_display: "Monthly",
            cta: "Subscribe Now",
            features: ["Exclusive content", "Ad-free experience", "Priority support"]
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PostPublicationsPublicationIdTiersRequest

requestOptions: TiersClient.RequestOptions

client.tiers.index(publicationId, { ...params }) -> Beehiiv.IndexTiersResponse

📝 Description

Retrieve all tiers belonging to a specific publication

🔌 Usage

await client.tiers.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.GetPublicationsPublicationIdTiersRequest

requestOptions: TiersClient.RequestOptions

client.tiers.show(publicationId, tierId, { ...params }) -> Beehiiv.TierResponse

📝 Description

Retrieve a single tier belonging to a specific publication

🔌 Usage

await client.tiers.show("pub_00000000-0000-0000-0000-000000000000", "tier_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

tierId: Beehiiv.TierId — The prefixed ID of the tier object

request: Beehiiv.GetPublicationsPublicationIdTiersTierIdRequest

requestOptions: TiersClient.RequestOptions

client.tiers.put(publicationId, tierId, { ...params }) -> Beehiiv.TierResponse

📝 Description

Update an existing tier belonging to a specific publication

🔌 Usage

await client.tiers.put("pub_00000000-0000-0000-0000-000000000000", "tier_00000000-0000-0000-0000-000000000000", {
    name: "Gold",
    description: "Our premium tier with exclusive benefits",
    prices_attributes: [{
            id: "price_00000000-0000-0000-0000-000000000000",
            currency: "usd",
            amount_cents: 500,
            interval: "month",
            interval_display: "Monthly",
            cta: "Subscribe Now",
            features: ["Exclusive content"],
            "delete": true
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

tierId: Beehiiv.TierId — The prefixed ID of the tier object

request: Beehiiv.UpdatePutTierRequest

requestOptions: TiersClient.RequestOptions

client.tiers.patch(publicationId, tierId, { ...params }) -> Beehiiv.TierResponse

📝 Description

Update an existing tier belonging to a specific publication

🔌 Usage

await client.tiers.patch("pub_00000000-0000-0000-0000-000000000000", "tier_00000000-0000-0000-0000-000000000000", {
    name: "Gold",
    description: "Our premium tier with exclusive benefits",
    prices_attributes: [{
            id: "price_00000000-0000-0000-0000-000000000000",
            currency: "usd",
            amount_cents: 500,
            interval: "month",
            interval_display: "Monthly",
            cta: "Subscribe Now",
            features: ["Exclusive content"],
            "delete": true
        }]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

tierId: Beehiiv.TierId — The prefixed ID of the tier object

request: Beehiiv.UpdatePatchTierRequest

requestOptions: TiersClient.RequestOptions

Webhooks

client.webhooks.create(publicationId, { ...params }) -> Beehiiv.WebhookResponse

📝 Description

Create a new webhook for a given publication.

🔌 Usage

await client.webhooks.create("pub_00000000-0000-0000-0000-000000000000", {
    url: "https://example.com/webhook",
    event_types: ["post.sent"]
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.PostWebhooksRequest

requestOptions: WebhooksClient.RequestOptions

client.webhooks.index(publicationId, { ...params }) -> Beehiiv.IndexWebhooksResponse

📝 Description

Retrieve all webhooks belonging to a specific publication.

🔌 Usage

await client.webhooks.index("pub_00000000-0000-0000-0000-000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

request: Beehiiv.GetWebhooksRequest

requestOptions: WebhooksClient.RequestOptions

client.webhooks.show(publicationId, endpointId) -> Beehiiv.WebhookResponse

📝 Description

Retrieve a specific webhook belonging to a publication.

🔌 Usage

await client.webhooks.show("pub_00000000-0000-0000-0000-000000000000", "ep_0000000000000000000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

endpointId: Beehiiv.EndpointId — The prefixed ID of the webhook object

requestOptions: WebhooksClient.RequestOptions

client.webhooks.update(publicationId, endpointId, { ...params }) -> Beehiiv.WebhookResponse

📝 Description

Update a webhook subscription for a publication.

🔌 Usage

await client.webhooks.update("pub_00000000-0000-0000-0000-000000000000", "ep_0000000000000000000000000000", {
    event_types: ["post.sent", "subscription.confirmed"],
    description: "A webhook to receive new posts data and new subscription confirmations."
});

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

endpointId: Beehiiv.EndpointId — The prefixed ID of the webhook object

request: Beehiiv.UpdateWebhookRequest

requestOptions: WebhooksClient.RequestOptions

client.webhooks.delete(publicationId, endpointId) -> Beehiiv.WebhooksDeleteResponse

📝 Description

Delete a webhook subscription from a publication.

🔌 Usage

await client.webhooks.delete("pub_00000000-0000-0000-0000-000000000000", "ep_0000000000000000000000000000");

⚙️ Parameters

publicationId: Beehiiv.PublicationId — The prefixed ID of the publication object

endpointId: Beehiiv.EndpointId — The prefixed ID of the webhook object

requestOptions: WebhooksClient.RequestOptions

client.webhooks.test(publicationId, endpointId) -> Beehiiv.GetPublicationsPublicationIdWebhooksWebhookIdTestsResponse

📝 Description

Send test info to an already set up webhook endpoint.

🔌 Usage

await client.webhooks.test("pub_00000000-0000-0000-0000-000000000000", "ep_0000000000000000000000000000");

⚙️ Parameters

publicationId: string — The prefixed ID of the publication object

endpointId: Beehiiv.EndpointId — The prefixed ID of the webhook object

requestOptions: WebhooksClient.RequestOptions

Workspaces

client.workspaces.identify() -> Beehiiv.WorkspaceIdentifyResponse

📝 Description

Retrieve information about the workspace the OAuth or API token is associated with.

🔌 Usage

await client.workspaces.identify();

⚙️ Parameters

requestOptions: WorkspacesClient.RequestOptions