Getting started with Klaviyo

Install the Firmhouse Klaviyo app to keep customer profiles up to date, use customer segments, and build flows around subscription activity.

The native integration is currently in Preview. Ask Firmhouse to enable Native Klaviyo integration for your project if you do not see Connect Klaviyo in the app settings.

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

Feature	How you can use it
Customer profile synchronization	Keep subscription counts, statuses, plans, and products available for Klaviyo segments and flow conditions.
Additional profile properties	Add selected Firmhouse data, such as next billing dates and customer references, to Klaviyo profiles.
Lifecycle events	Trigger flows when subscriptions, orders, payments, and other records change.
Segment synchronization	Bring Klaviyo audiences into Firmhouse to filter subscriptions and target offers.
Customer Portal personalization	Use Klaviyo properties and segment membership in Customer Portal v2 templates.

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. On the Setup tab, click Connect Klaviyo.
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.

Synchronize customer profiles

Firmhouse will automatically keep Klaviyo profiles up to date with your customers’ subscription details.

Subscriptions using the same email address in your project share one Klaviyo profile. Firmhouse combines their details 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 six standard properties. They are always included when profiles are synchronized and cannot be renamed or removed.

Klaviyo property	Value
firmhouse_subscription_count	Number of completed subscriptions, including past subscriptions.
firmhouse_first_subscription_products	Distinct product names from the first subscription account, including products later removed.
firmhouse_current_subscription_count	Number of current subscriptions: active, paused, cancellation in progress, or pending cancellation.
firmhouse_subscription_statuses	List of distinct subscription statuses.
firmhouse_current_plan_names	List of distinct plan names on current subscriptions.
firmhouse_current_product_names	List of distinct product names on current subscriptions.

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.

Add optional properties

1. Open Profile properties and click Add property.
2. Choose a source and enter the property key you want to use in Klaviyo.
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.

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. Events start turned off, so you can review them before they trigger flows.

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, then turn on the event.
3. Use Configure to inspect or customize its payload. If a newer default payload is available, use Review update before applying it; 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.

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:

Metric	Possible flow
Firmhouse: Subscription activated	Welcome a customer after activation.
Firmhouse: Subscription paused	Explain what happens while a subscription is paused.
Firmhouse: Payment failed	Help a customer resolve a failed payment.
Firmhouse: Upcoming order notice	Remind a customer about an upcoming order and available actions.

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.

Use Configure on the lifecycle event to review its 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. Click Sync all to import the segment list and synchronize enabled segments.
2. Use each segment’s switch to choose whether Firmhouse synchronizes its membership.
3. Use Refresh to update an enabled segment, and check its Last synced status.
4. 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.

Turning off a segment stops membership fetching and removes its subscription memberships in Firmhouse. It does not delete the segment in Klaviyo. 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

Area	After installing the app
Installation	Install the Firmhouse app in your existing Klaviyo account.
Transactional event names and payloads	Existing saved values are preserved.
Customer communication channel	Your existing choice remains in place.
Event configuration	Configure and test v2 events from the Lifecycle events tab. The Email configuration editor remains part of v1.
Profile synchronization	Available independently of the communication channel; enabled by default unless previously turned off.
Lifecycle events	Separate, opt-in metrics; existing transactional events and custom webhooks are not migrated into them.
Klaviyo segments	Available to synchronize into Firmhouse and use for subscription filtering and offer targeting.

1. Prepare your existing setup

Ask Firmhouse to enable the Native Klaviyo integration preview for your project. Then 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. On Setup, 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 New permissions required, use Reconnect Klaviyo to approve the requested access.

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, then turn it on.
3. Use Configure 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.

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 Setup, check Customer profile synchronization and save. 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, click Sync all, and choose which segments to synchronize. Check the matching subscription counts and use Refresh when needed.

Customer Portal: Use Klaviyo profile data and segment membership to personalize Customer Portal v2.

You can install the new app without enabling every feature. The sections above cover each feature in detail.

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

Connect Klaviyo is missing: Ask Firmhouse to enable the native integration preview for your project.

New permissions are required: Click Reconnect Klaviyo, approve access for the same account, and confirm that Firmhouse shows it as connected.

Profile properties are missing: Check that the app and customer profile synchronization are enabled, 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 event is enabled and available for your project. Inspect its payload and send a test where supported. Installing the app alone does not enable lifecycle events.

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.

Related articles

• Klaviyo v1: transactional email setup
• Klaviyo metrics via outgoing webhooks
• Integrate Klaviyo data in Customer Portal v2