sales-skills/sales-beehiiv

Beehiiv Platform Help

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

Ask the user:

1. What area of beehiiv do you need help with?

   • A) Publishing — editor, templates, scheduling, content
   • B) Audience growth — Boosts, referral program, recommendations, subscribe forms
   • C) Monetization — Ad Network, paid subscriptions, sponsorship storefront, digital products
   • D) Automations — email flows, segments, triggers
   • E) Website — builder, custom domains, SEO, landing pages
   • F) Analytics — campaign stats, subscriber metrics, A/B testing
   • G) Integrations — Zapier, Make, webhooks, API
   • H) Account — pricing, plan features, billing, teams
   • I) Something else — describe it

2. What plan are you on?

   • A) Launch (free — up to 2,500 subscribers)
   • B) Scale (from $43/mo billed annually, $49/mo monthly — up to 100K subscribers)
   • C) Max (from $96/mo billed annually, $109/mo monthly — up to 100K subscribers)
   • D) Enterprise (custom — 100K+ subscribers)
   • E) Not sure

3. What are you trying to accomplish? (describe your specific goal or question)

Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.

Step 2 — Route or answer directly

If the request maps to a strategy skill, route:

• Newsletter monetization strategy → "This is a monetization strategy question — run: /sales-newsletter {your question}"
• Growing subscriber list strategy → "This is an audience growth question — run: /sales-audience-growth {your question}"
• Email marketing strategy (sequences, segmentation) → "This is an email marketing question — run: /sales-email-marketing {your question}"
• Email deliverability / SPF / DKIM → "This is a deliverability question — run: /sales-deliverability {your question}"
• Selling digital products → "This is a digital products question — run: /sales-digital-products {your question}"

If the request is beehiiv-specific (platform config, feature questions, troubleshooting), continue to Step 3.

Step 3 — Beehiiv platform reference

Read references/platform-guide.md for the full platform reference — modules, pricing, integrations, data model, workflows.

Answer the user's question using only the relevant section. Don't dump the full reference.

If the question involves the API, also read references/beehiiv-api-reference.md for endpoint details.

Step 4 — Actionable guidance

You no longer need the platform guide — focus on the user's specific situation.

Provide step-by-step guidance tailored to their plan tier:

• Check if the feature they need is available on their plan (many features are Scale+ only)
• If they're on Launch and need a paid feature, explain the upgrade path
• For API questions, provide example requests with their publication context
• For growth questions, recommend the beehiiv-native approach first, then third-party alternatives

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.

Gotchas

Best-effort from research — review these, especially items about plan-gated features and integration gotchas that may be outdated.

1. Shared IP deliverability — all beehiiv users share sending infrastructure. If deliverability drops, it may not be your fault. Custom domains help, but dedicated IPs require Enterprise plan.
2. Automations are limited — email automations can only look back 30 days. You can't import complex flows from other platforms that use longer time windows.
3. Scale plan required for monetization — Ad Network, Boosts, paid subscriptions, and digital products all require Scale (from $43/mo annual, $49/mo monthly) or higher. The free Launch plan has no monetization features.
4. Webhooks require Scale plan — can't receive real-time events on the free plan.
5. Send API is Enterprise-only and in beta — programmatic email sending is beta, available on request to Enterprise plans. The regular API (subscriptions, posts list/get, publications, segments, tiers, custom fields, webhooks, etc.) is available on all plans.
6. Create-post API is Enterprise-only — the POST /posts endpoint requires Enterprise plan access.
7. API rate limit is 180 req/min per organization — not per API key. All org keys share the budget. Exceeding returns 429; back off using the RateLimit-Remaining / RateLimit-Reset response headers.
8. Webhook tier events use dot notation — the four tier events are subscription.tier.created, subscription.tier.deleted, subscription.tier.paused, subscription.tier.resumed (NOT tier_added/tier_paused). "Tier added" is named tier.created. Webhook payloads have no documented HMAC signature — re-fetch by ID to validate rather than trusting the payload.
9. Subscriber pricing scales steeply — Scale and Max both cap at 100K subscribers. Beyond that, you must upgrade to Enterprise (custom pricing). The jump can be significant.
10. Open rate concerns — some users report beehiiv open rates appear higher than expected compared to other platforms. Use click rates as a more reliable engagement metric.

Related skills

• /sales-newsletter — Newsletter monetization strategy (paid subscriptions, sponsorships, ad sales, pricing)
• /sales-audience-growth — Growing your subscriber list (lead magnets, referral programs, cross-promotion)
• /sales-email-marketing — Email marketing strategy (sequences, automation, segmentation)
• /sales-deliverability — Email deliverability (SPF, DKIM, DMARC, shared vs dedicated IPs)
• /sales-digital-products — Selling digital products (ebooks, templates, courses)
• /sales-kit — Kit platform help (if considering alternatives)
• /sales-ghost — Ghost platform help (if considering alternatives)
• /sales-buttondown — Buttondown platform help (if considering alternatives)
• /sales-sparkloop — SparkLoop platform help (referral programs, paid recommendations)
• /sales-paved — Paved platform help (newsletter sponsorship marketplace)
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do

Examples

Example 1: Monetization not working

User says: "I set up the ad network on beehiiv but I'm barely making any money" Skill does: Checks plan tier (must be Scale+), reviews subscriber count and engagement metrics, explains how ad network revenue scales with list size and niche, suggests optimizing content for higher engagement, recommends trying Boosts alongside ads, and provides realistic revenue benchmarks Result: User understands ad network expectations and has concrete steps to increase revenue

Example 2: Migration from another platform

User says: "I'm moving from Substack to beehiiv — what do I need to know?" Skill does: Walks through subscriber import process, content migration, custom domain setup, differences in monetization (Substack 10% fee vs beehiiv 0%), feature comparison (automations, referral program, analytics), and gotchas (automation limitations, plan-gated features) Result: User has a complete migration plan with platform-specific considerations

Example 3: API integration

User says: "I want to automatically create subscribers in beehiiv when someone fills out a Typeform" Skill does: Explains the POST /subscriptions endpoint, provides example request with required fields, shows webhook/Zapier alternatives for no-code, notes that API access is available on all plans, and covers custom fields for additional data Result: User has working API integration code or a Zapier workflow

Troubleshooting

Emails going to spam

Symptom: Subscribers report newsletters landing in spam/promotions Cause: Shared IP infrastructure, missing custom domain, low engagement dragging reputation Solution: Set up a custom sending domain. Ask engaged subscribers to move emails to primary inbox and reply. Clean inactive subscribers regularly. If persistent, contact beehiiv support — it may be a platform-wide issue. Dedicated IPs require Enterprise plan.

Paid subscriptions not working

Symptom: Stripe payments failing, subscribers can't upgrade, paywall not showing Cause: Stripe connection issues, plan limitations, or misconfigured premium tiers Solution: Verify Stripe is properly connected (Settings > Payments). Check you're on Scale+ plan. Ensure premium tier is configured with correct pricing. Test in incognito mode. Check beehiiv support article on troubleshooting paid subscriptions.

Referral program low participation

Symptom: Referral program launched but very few subscribers are sharing Cause: Rewards aren't compelling, sharing link isn't prominent, or subscribers don't know it exists Solution: Mention the referral program in every newsletter (dedicated section or footer). Make rewards achievable at low tiers (1-3 referrals). Provide pre-written share text. Show a progress tracker in emails.