Skip to main content
Existing API-key connections keep working. Connect with OAuth from Apps > Klaviyo > Configure when you are ready to use the new integration.
Install the Firmhouse Klaviyo app to build customer segments, personalize messages, and trigger flows from subscription activity. Klaviyo v2 keeps your customer and subscription data up to date in Klaviyo and lets you choose which events to use in your flows.

​
Migrate from Klaviyo v1 to Klaviyo v2

Already using the previous Klaviyo integration? Follow the migration steps to install the new app and set up its features while keeping your existing flows working.

​
What you can do with the new Klaviyo integration

Firmhouse sends data and events; you create the segments, flows, and messages in Klaviyo. Installing the app does not create or publish Klaviyo flows.

​
Install the Firmhouse Klaviyo app

  1. In Firmhouse, open Apps > Klaviyo > Configure.
  2. Click Connect Klaviyo. Account details are shown on the Configuration tab.
  3. Sign in to the Klaviyo account you want to use and approve the requested access.
  4. Return to Firmhouse. Check that Account connection confirms your account is connected and shows the expected account name.
Customer profiles and Klaviyo segments synchronize automatically while the native integration is enabled and connected. On a first connection with no legacy API key, legacy events editor, or existing managed lifecycle events, Firmhouse also enables all lifecycle events supported by your project. Existing installations and v1 migrations keep their event choices. Review existing Klaviyo flows before connecting a new project, then check the enabled events after connecting. Installing the app does not change how Firmhouse sends customer emails. When your Klaviyo flows are tested and live, open Settings > Email configuration > General and select Email flows via the new Klaviyo integration under Send emails to customers with. See Configure email notifications. Profile synchronization and enabled lifecycle events also work while built-in Firmhouse emails remain selected; check for overlapping messages.

​
Connection status and recovery

Open Apps > Klaviyo > Configure and check the account on Configuration: Firmhouse refreshes expiring OAuth tokens automatically. If access is revoked or the refresh token is rejected, reauthorize when prompted. Reauthorization is different from disconnecting the account: disconnecting removes synchronized segments from Firmhouse. Test mode applies to legacy API-key setups preparing notification events before switching the email channel. It is not an OAuth sandbox mode. A connected native integration can send enabled lifecycle events independently of the email channel.

​
Synchronize customer profiles

Firmhouse automatically synchronizes customer name, phone number, address, and subscription properties to Klaviyo while the native integration is enabled and connected. Completed signups using the same email address in your project share one Klaviyo profile; email matching ignores letter case. Firmhouse combines their subscription properties on that profile. For example, if a customer has two active subscriptions—one for coffee and one for tea—their profile shows two current subscriptions and lists both products. Use event details when a flow needs information about one specific subscription.

​
Standard properties

The Profile properties tab shows the standard properties. They are always included when profiles are synchronized and cannot be renamed or removed. For example, build a Klaviyo segment where firmhouse_current_subscription_count is greater than zero to find customers with a current subscription. This includes paused subscriptions. Combine it with status conditions when your audience needs a narrower definition. To find customers subscribed to a particular product, use firmhouse_current_recurring_product_ids containing its Firmhouse product ID. For example, a customer who bought deodorant once and subscribes to razors will match the razor product ID, but not the deodorant product ID. Product IDs stay the same when a product is renamed. Recurring products include products charged or shipped repeatedly, including the default product in a product queue. Individual queue entries and one-off add-ons are excluded. These lists include paused subscriptions and are empty when no recurring products qualify. Run Synchronize all profiles to populate these properties for existing customers before using them in a segment. Compare Klaviyo’s profile count with unique customer email addresses in Firmhouse; several subscriptions can share one profile.

​
Add optional properties

  1. Open Profile properties and click Add property.
  2. Enter Property name in Klaviyo and choose a predefined source under Value to send.
  3. Click Save profile properties.
Available sources include current or historical subscription IDs, whether a current subscription exists, current plan and product IDs, Shopify variant IDs, customer references, next billing dates, and your project’s ID, name, and currency. Firmhouse prefixes keys with firmhouse_; standard property keys are reserved. Property values use the source’s data type: counts and project IDs are numbers, subscription IDs and statuses are lists, and Has a current subscription is a boolean. This editor uses predefined sources rather than custom Liquid expressions. Liquid JSON templates are available separately for lifecycle event payloads. Removing or renaming a configured key clears the old property’s value on a subsequent profile synchronization. Review Klaviyo segments and flow conditions that use that key before changing it.

​
Update existing customers

Subscription changes synchronize automatically. To populate existing customers or apply changed property mappings across them, open Profile properties and click Synchronize all profiles. Follow the progress shown beside the button, then inspect a known customer’s profile in Klaviyo. The synchronization processes completed signups with an email address. It updates profile data; it does not replay historical lifecycle events.

​
Send lifecycle events

The Lifecycle events tab lets you choose which Firmhouse events become Klaviyo metrics. New v2-only connections enable all supported events automatically. Existing installations and v1 migrations keep their saved choices; reconnecting does not turn on every event. You can switch individual events on or off, or use Enable all and Disable all. Available categories include subscriptions, plans, subscription products, orders, invoices, payments, returns, acceptance checks, collection cases, retention, offers and referrals, customer access, assets, and customer details. The events shown depend on your project’s setup. See Available lifecycle events for the full list and the properties each event sends.
  1. Open Lifecycle events and find the event you need.
  2. Review the metric name and included properties, and check whether the event is enabled.
  3. For a configured event, expand Customize event payload and click Edit payload template to inspect or customize its Liquid JSON. If a newer default is available, click Load update into editor, review it, then Save changes. Saved payloads are not silently replaced.
  4. Send a test event where that control is available, or trigger the event with a test subscription.
  5. Check the received metric and properties in Klaviyo before using it in a live flow.
The Outstanding invoices event has no test-event control. Trigger it with a test subscription that is marked as non-paying and has outstanding invoices, or rehearse your flow with the sendSubscriptionKlaviyoEvent GraphQL mutation. See Outstanding invoices for details. If an event is already configured as a custom Klaviyo webhook, manage that existing webhook through Klaviyo metrics via outgoing webhooks.

​
Build flows around events

Examples of flow starting points include: In Klaviyo, choose the received metric as the flow trigger, inspect its event properties, and design your message. Use event data for the subscription or order that triggered the flow and profile properties for the customer’s current overall state. Test the flow before making it live, including any conditions that should stop a message when the customer’s situation changes.

​
Personalize event messages

The upcoming-order lifecycle payload includes a products list with names, quantities, SKUs, images, and product identifiers. It also includes order counts and Customer Portal action links. Offers can include product details and signed acceptance links when eligible. Expand Customize event payload and click Edit payload template to review the payload, then use the actual test event to select variables in Klaviyo. Your saved payload may differ from the latest default.

​
Bring Klaviyo segments into Firmhouse

Create your audience definitions in Klaviyo, then open Klaviyo segments in Firmhouse:
  1. Wait for the automatic synchronization to import the segment list and its memberships.
  2. Use Refresh to update a segment sooner, and check its Last synced status.
  3. Click the subscription count to view the matching subscriptions.
Firmhouse matches segment profiles to completed subscriptions by email address. One Klaviyo profile can therefore correspond to multiple Firmhouse subscriptions, so the two membership counts can differ. Scheduled synchronization runs hourly; changes are not instantaneous. Firmhouse checks each segment’s Klaviyo profile count before synchronizing it. Segments with more than 100,000 profiles are shown as Not synced and their stored Firmhouse memberships are removed. If a segment later falls to 100,000 profiles or fewer, it joins the next synchronization automatically. Eligible segments synchronize automatically; there is no per-segment switch or Sync all control. A segment removed in Klaviyo is removed from Firmhouse on a subsequent synchronization. Use synchronized segments in promotional offer conditions. Projects with the separate Klaviyo Segments in Analytics preview can also filter cohort and lifetime value reporting by synchronized segments.

​
Personalize the Customer Portal

Customer Portal v2 Liquid templates can use synchronized segment membership to show a message or product action to a specific audience, such as VIP customers. Use subscription.segments for enabled memberships stored in Firmhouse. See Use Klaviyo segments in the Customer Portal for typed fields, examples, and synchronization steps. Template preview uses stored membership too; use Refresh and check Last synced before testing a segment change.

​
Migration steps

Klaviyo v1 is the previous integration for sending Firmhouse email notification events to Klaviyo. The new Firmhouse Klaviyo app adds customer profile updates, segment synchronization, and events you can enable and configure individually. Install the app in the same Klaviyo account to keep your existing metrics and flows in that account. Your saved transactional event names and JSON payloads remain in place. Migration does not require replacing them with lifecycle events.

​
What changes

​
1. Prepare your existing setup

Before connecting, check:
  • Which Klaviyo account the existing public API key belongs to.
  • The metric names used by your active transactional flows.
  • Your current customer communication channel and any custom Klaviyo metric webhooks.
  • Any Zapier automation that writes Firmhouse profile data to Klaviyo. Compare its property keys with the new native properties before deciding whether to retire it.
Keep existing flows active during installation. Installing the app in a different Klaviyo account will not transfer that account’s flow definitions or event history.

​
2. Install the app in the same Klaviyo account

  1. Open Apps > Klaviyo > Configure in Firmhouse.
  2. Click Connect Klaviyo.
  3. Sign in to the existing Klaviyo account and approve access.
  4. Confirm that Firmhouse shows the expected account name and that the account is connected.
If you see Klaviyo permissions required, use Reauthorize Klaviyo to approve the requested access. For More Klaviyo features available, use Update Klaviyo permissions.

​
3. Configure and test v2 events

  1. Open Apps > Klaviyo > Lifecycle events and select an event you want to use.
  2. Review its metric name and properties, and enable it if needed.
  3. Expand Customize event payload and click Edit payload template to inspect or customize its payload.
  4. Send a test event to an address you control where the test control is available, or trigger the event with a test subscription.
  5. Inspect the received event in Klaviyo and build or adapt your flow using that metric and its properties.
The Outstanding invoices event has no test-event control. Trigger it with a test subscription that is marked as non-paying and has outstanding invoices, or rehearse your flow with the sendSubscriptionKlaviyoEvent GraphQL mutation. See Outstanding invoices for details. V2 lifecycle metrics are separate from your existing v1 metrics. Keep existing v1 flows working while testing the new flow, and prevent overlapping messages before making it live. Installing the app preserves saved v1 event templates but does not convert them into v2 lifecycle events.

​
4. Populate profile properties

On Configuration, confirm that Customer profiles shows Automatic sync enabled. Review the standard properties and any additional mappings on Profile properties, then click Synchronize all profiles to update existing customers. Check a customer with a known subscription in Klaviyo. If they have multiple subscriptions using the same email address, the profile properties aggregate them. Review segments and conditions accordingly: for example, the current subscription count includes paused subscriptions. The full synchronization updates profile data. It does not send a history of lifecycle events or rebuild past flow activity. See the profile property reference.

​
5. Adopt new features as needed

Lifecycle events: Review and enable events individually. Inspect a received event before creating a flow around it. Existing transactional flows and custom metric webhooks remain separate; enabling a similar lifecycle flow can otherwise send a second message for the same action. Segments: Open Klaviyo segments after automatic synchronization has imported the segment list. Check the matching subscription counts and use Refresh when needed. Customer Portal: Use Klaviyo profile data and segment membership to personalize Customer Portal v2. Profile and segment synchronization are automatic while the native integration is enabled and connected. You choose which lifecycle events and Klaviyo flows to use. Once your replacement email flows are tested and live, select Email flows via the new Klaviyo integration in Settings > Email configuration > General. Keep the legacy email channel until its replacement flows cover the notifications you need.

​
Before retiring an old flow or automation

Verify the new behavior with a test customer, including payload properties, flow conditions, and actual message delivery. Replace one use case at a time. Keep required transactional notifications covered throughout the change. Disconnecting the Klaviyo account removes synchronized Klaviyo segments from Firmhouse. A stored legacy public API key may still support legacy event delivery, but it cannot provide native profile or segment synchronization. Contact Firmhouse if you need help reverting the connection without disrupting your setup.

​
Troubleshooting

Authorization was revoked or cannot refresh: Open Apps > Klaviyo > Configure, click Reauthorize Klaviyo, approve access for the same account, and confirm the connection is restored. New permissions are required: Use Reauthorize Klaviyo for required permissions or Update Klaviyo permissions for additional features, then approve access for the same account. Profile properties are missing: Check that the app is enabled and connected, that the customer completed signup with an email address, and that you are inspecting the matching Klaviyo profile. Run Synchronize all profiles for existing customers. A lifecycle metric is missing: Check that the app is enabled and connected and that the event is enabled and available for your project. Existing installations may have events turned off. Inspect its payload and send a test where supported. Enabling an event does not replay earlier activity. A customized payload fails: Open Customize event payload > Edit payload template, check the validation feedback, and correct the Liquid JSON. The rendered payload must be a JSON object. Check the received test event in Klaviyo before relying on its properties. For legacy transactional templates, use Klaviyo v1 troubleshooting. An email arrives twice: Check whether multiple flows or notifications send a message for the same customer action. Segment membership looks stale: Check the last synchronization time and use Refresh for the segment. Check its definition and membership in Klaviyo as well. Disconnecting the account: Disconnecting removes synchronized Klaviyo segments from Firmhouse. Check flows, offers, and portal personalization before disconnecting.