> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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.
</Info>

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](#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](/integrations/klaviyo/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](/integrations/klaviyo/metric-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](/configure/activation-and-cancellation/promotional-offers). 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 read Klaviyo profile properties and segment membership through `subscription.klaviyo_profile`. For example, show a message to a VIP audience or display a product recommendation based on a profile property.

See [Integrate data from Klaviyo](/customer-portal-v2/integrate-klaviyo-data) for examples and caching behavior. Portal lookups and scheduled segment synchronization have different refresh behavior, so do not assume every surface updates at the same time.

## 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](/integrations/klaviyo/getting-started#standard-properties).

### 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](/customer-portal-v2/integrate-klaviyo-data).

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](/integrations/klaviyo/klaviyo-v1)
* [Klaviyo metrics via outgoing webhooks](/integrations/klaviyo/metric-webhooks)
* [Integrate Klaviyo data in Customer Portal v2](/customer-portal-v2/integrate-klaviyo-data)