🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Beehiiv Premium Add-on Setup Guide

Updated 5 min read Gravity Forms CRM & Email Marketing
On this page
  1. Step 1: Install and Activate Your License
  2. Step 2: Connect beehiiv
  3. Step 3: Create a Feed
  4. Custom Fields
  5. Double Opt-in, Welcome Email and Re-subscribing
  6. Attribution: UTM, Referral Code and Referring Page
  7. Newsletter Lists and Automations
  8. Existing Subscribers
  9. Consent and Conditional Logic
  10. Entry Notes, Resend and Failures
  11. Troubleshooting & FAQ
  12. The connection fails with “rejected the API key”.
  13. A custom field is not filled.
  14. Why is the status “validating”?
  15. Can one form sign people up to two publications?

The Gravity Forms Beehiiv Premium Add-on adds the people who fill in your forms to your beehiiv newsletter. Choose the publication, fill custom fields, add tags, decide on double opt-in and the welcome email, keep UTM and referral attribution, and put subscribers on newsletter lists and into automations.

This guide covers installation, connecting beehiiv, creating a feed, custom fields, attribution, lists and automations, existing and unsubscribed people, consent and troubleshooting.

System Requirements & Prerequisites

  • WordPress: Version 6.5 or higher
  • PHP: Version 7.4 or higher
  • Gravity Forms: Version 2.9 or higher, any licence
  • beehiiv: Any plan — API access is part of every plan, including the free Launch plan. The number of API requests per minute depends on your plan.
  • GravityExtra license: The add-on installed, activated and licensed with an active GravityExtra license key

Step 1: Install and Activate Your License

  1. In WordPress go to Plugins → Add New → Upload Plugin, upload the add-on ZIP file and click Activate.
  2. Go to Forms → Settings → Beehiiv. The Gravity Extra License section is at the top.
  3. Paste your license key from your GravityExtra account (My Account → License keys) and click Activate License. The beehiiv account settings appear below once the license is active.

Step 2: Connect beehiiv

  1. In beehiiv, open Settings, scroll to Workspace Settings → API and click Create New API Key. Copy the key; beehiiv shows it only once. You need the Owner or Admin role, and beehiiv may ask you to verify your identity before it enables API keys. You can limit a key to one publication.
  2. Paste it into API key and click Save Settings. The page shows how many publications the key can reach, for example “Connected to beehiiv: 2 publications”.
  3. The key is never shown again; the field only tells you its last four characters. Leave it empty later to keep it.
  4. Optional: enter a Backup email for failed submissions, so a sign-up beehiiv cannot accept is never lost.
Beehiiv settings page in Gravity Forms with the GravityExtra license section, a saved beehiiv API key shown only by its last four characters, a Connected to beehiiv with 2 publications status and a backup email address
The license section comes first, then your beehiiv API key.

Step 3: Create a Feed

  1. Open the form, go to Settings → Beehiiv and click Add New.
  2. Choose the Publication. The page reloads to show that publication’s custom fields, newsletter lists and automations.
  3. Map the Email field.
  4. Map Custom fields: pick a beehiiv field on the left and a form field on the right. The field type is shown next to its name.
  5. Add Tags such as website, {form_title}. New tags are created in beehiiv automatically.
  6. Choose the Double opt-in behaviour and whether new subscribers get the welcome email, then save the feed.
Beehiiv feed: publication Northwind Weekly, email mapped, custom fields First Name, Company Size, Wants Deals, Birthday and Role mapped to form fields with their types, tags, double opt-in on, welcome email, UTM option, update existing subscribers, the Weekly Digest newsletter list and the Welcome series automation ticked
One feed: publication, custom fields, tags, opt-in, lists and automations.

Custom Fields

Custom fields must exist in beehiiv first (Audience → Custom fields). Values are sent in the type of the field: integer and double fields receive numbers, boolean fields are true for any value except empty, 0, no, false or off, and date fields receive the date as YYYY-MM-DD whatever format your form shows. If beehiiv drops a value — for example because a field was renamed — the entry note says which one.

Double Opt-in, Welcome Email and Re-subscribing

  • Use the publication setting follows the double opt-in choice of your publication. On always sends a confirmation email first; Off subscribes straight away. Subscribers waiting for confirmation have the status validating or pending.
  • Send the welcome email to new subscribers is on by default.
  • Re-subscribe people who unsubscribed before is off by default: someone who unsubscribed is left alone and the entry note says so. Turn it on only when the form clearly asks people to subscribe, for example with a consent checkbox.

Attribution: UTM, Referral Code and Referring Page

With Read UTM parameters and the referring page from the page address on, the add-on sends utm_source, utm_medium, utm_campaign, utm_term and utm_content from the address of the page with the form, the page itself as the referring site, and a ?ref= code as the referral code, so the subscriber who shared the link gets credit in your referral program.

In the Attribution section you can map form fields instead, for example a hidden field filled by your own tracking script. A mapped field wins over the page address.

Beehiiv feed Attribution section with optional form fields for utm_source, utm_medium, utm_campaign, utm_term, utm_content and referral code, and the conditional logic section below
Optional attribution fields and conditional logic.

Newsletter Lists and Automations

The newsletter lists and the automations of the chosen publication are listed as checkboxes. New subscribers are added to the ticked lists and automations in the same request. For existing subscribers, ticked lists are added (never removed) and each ticked automation is started separately.

beehiiv only accepts subscribers in automations that have an active Add by API trigger. If an automation refuses the subscriber, the subscription is still saved and the entry note tells you to check the trigger.

Existing Subscribers

The add-on first looks the email address up in the publication. For an active subscriber, Update their custom fields and lists saves the new values; Keep them as they are only adds the tags and automations. Nobody is subscribed twice.

Add a checkbox such as “Yes, send me the newsletter” to contact or order forms and turn on Conditional logic at the bottom of the feed: subscribe only when that box is ticked. You can also add several feeds, for example one per publication.

Entry Notes, Resend and Failures

  • Each entry gets a note with the subscription ID and its status, such as “beehiiv: new subscriber sub_… (status: validating).”, and the beehiiv box on the entry page shows the same.
  • When beehiiv refuses a sign-up, the note shows its message; the details go to the backup email and the Send to beehiiv again button retries the entry.
  • When the API limit of your plan is reached, a wait of up to 5 seconds is retried once; otherwise the note says when to try again.
  • With Gravity Forms logging on, only subscription IDs and HTTP status codes are logged — never email addresses or the API key.

Troubleshooting & FAQ

The connection fails with “rejected the API key”.

Create a new key in Settings → Workspace settings → API and paste it again. Deleted keys stop working immediately.

A custom field is not filled.

Check that the field exists in the chosen publication with the same name. Click Test connection in the add-on settings to reload the lists after adding fields in beehiiv.

Why is the status “validating”?

beehiiv checks new addresses and, with double opt-in, waits for the confirmation click. The subscriber becomes active afterwards.

Can one form sign people up to two publications?

Yes. Add one feed per publication, each with its own fields, tags and lists.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr