Integrate data from Klaviyo

Customer Portal v2 templates can read Klaviyo profile properties and segment membership for the customer that is logged in. Use this when you want to personalize the portal based on data you already maintain in Klaviyo. For example, you can:

Show a VIP message to customers in a VIP members segment
Show a product recommendation when a Klaviyo profile property has a certain value
Hide or show a portal action based on campaign, loyalty, churn-risk, or lifecycle data
Pair a personalized Customer Portal message with a Klaviyo metric that tracks when a customer acts on it

Before you start

You need:

Customer Portal v2 enabled for your project
The Native Klaviyo integration preview enabled for your project
Permission to connect your Klaviyo account to Firmhouse
Access to Customer Portal > Templates so you can edit Liquid templates

Ask Firmhouse to enable Native Klaviyo integration for your project if you do not see the OAuth connection option in the Klaviyo app settings.

Connect Klaviyo with OAuth

In Firmhouse, open Apps > Klaviyo.
Click Connect Klaviyo.
Sign in to Klaviyo and approve the requested access.
Return to Firmhouse and confirm that the Klaviyo settings show OAuth connected.

Firmhouse requests access to send events, read profiles and segments, and keep customer profile properties current. OAuth tokens are stored encrypted and refreshed automatically. You do not need to create or paste a private API key. If Firmhouse shows New permissions required, click Reconnect Klaviyo and approve the current permissions. Legacy public API keys can still send existing Klaviyo metric events, but they cannot read profile properties or segment membership. Connect with OAuth to use Klaviyo data in Customer Portal templates. Read Klaviyo’s OAuth overview for more information about how Klaviyo authorizes connected applications.

Use the Klaviyo profile Liquid object

Klaviyo data is available through the current subscription:

{{ subscription.klaviyo_profile }}

The klaviyo_profile object exposes:

Property	Description
`properties`	The Klaviyo profile properties for the subscription email address.
`segments`	A list of segment objects with `id` and `name`.
`segment_ids`	A list of Klaviyo segment IDs.
`segment_names`	A list of Klaviyo segment names.

Firmhouse looks up the Klaviyo profile by the subscription email address. If Klaviyo is not connected with OAuth, the subscription has no email address, or Klaviyo does not return a profile, the object renders as empty data.

Show content based on a profile property

Use subscription.klaviyo_profile.properties when the decision is based on a custom property on the Klaviyo profile.

{% assign klaviyo_properties = subscription.klaviyo_profile.properties %}

{% if klaviyo_properties.customer_tier == "vip" %}
  <div class="rounded-lg border border-emerald-200 bg-emerald-50 p-4">
    <p class="font-semibold text-emerald-950">Thanks for being a VIP customer.</p>
    <p class="mt-1 text-sm text-emerald-900">
      Here is an extra recommendation for your next order.
    </p>
  </div>
{% endif %}

Klaviyo property keys can be accessed with dot notation when the key is Liquid-friendly, such as customer_tier. For keys with spaces or special characters, use bracket notation or normalize the property name in Klaviyo first.

{{ subscription.klaviyo_profile.properties["Customer Tier"] }}

Show content based on segment membership

Use segment_names when you want to check whether a customer is in a named Klaviyo segment.

{% assign klaviyo_segment_names = subscription.klaviyo_profile.segment_names %}

{% if klaviyo_segment_names contains "VIP members" %}
  <div class="rounded-lg border border-emerald-200 bg-emerald-50 p-4">
    <p class="font-semibold text-emerald-950">VIP members</p>
    <p class="mt-1 text-sm text-emerald-900">
      You are part of the VIP members segment in Klaviyo.
    </p>
  </div>
{% endif %}

Use segment_ids instead of segment_names when you want the template logic to keep working if a segment is renamed in Klaviyo.

{% assign klaviyo_segment_ids = subscription.klaviyo_profile.segment_ids %}

{% if klaviyo_segment_ids contains "SEGMENT_ID_FROM_KLAVIYO" %}
  <p>This message is shown for a specific Klaviyo segment.</p>
{% endif %}

Combine Klaviyo data with Customer Portal actions

You can combine Klaviyo conditions with Customer Portal components. For example, show an add-product action only for customers in a specific segment:

{% assign klaviyo_segment_names = subscription.klaviyo_profile.segment_names %}

{% if klaviyo_segment_names contains "VIP members" %}
  <div class="rounded-lg border border-gray-200 bg-white p-4">
    <p class="font-semibold text-gray-900">Add a VIP product to your next order</p>
    <p class="mt-1 text-sm text-gray-600">
      Choose an extra item and add it to your next shipment.
    </p>

    <div class="mt-4">
      {% add_product size: "small" %}
    </div>
  </div>
{% endif %}

Track Customer Portal actions in Klaviyo

Use Klaviyo’s public Client Event API when you want to track that a Customer Portal message was shown or clicked. This is a browser-side API, so use your Klaviyo public API key, also called the Site ID. Never expose OAuth access or refresh tokens in Customer Portal HTML or JavaScript. A practical pattern is to define one helper function in the shared_head template, and then call that helper from any page, dialog, or button where you want to track a Customer Portal action.

<script>
  window.trackKlaviyoCustomerPortalEvent = function(metricName, options = {}) {
    const publicApiKey = "PUBLIC_API_KEY_OR_SITE_ID";
    const email = options.email;
    const properties = options.properties || {};

    if (!publicApiKey || !email || !metricName) return Promise.resolve();

    return fetch(`https://a.klaviyo.com/client/events?company_id=${encodeURIComponent(publicApiKey)}`, {
      method: "POST",
      headers: {
        "Content-Type": "application/vnd.api+json",
        "revision": "2026-04-15"
      },
      body: JSON.stringify({
        data: {
          type: "event",
          attributes: {
            metric: {
              data: {
                type: "metric",
                attributes: {
                  name: metricName
                }
              }
            },
            profile: {
              data: {
                type: "profile",
                attributes: {
                  email: email
                }
              }
            },
            properties: properties
          }
        }
      })
    }).catch(function(error) {
      console.warn("Could not track Klaviyo event", error);
    });
  };
</script>

After that helper is available, call it from the template where the event happens. For example, track that a VIP dialog was shown:

{% if klaviyo_segment_names contains "VIP members" %}
  <script>
    window.trackKlaviyoCustomerPortalEvent("Viewed VIP Customer Portal offer", {
      email: "{{ subscription.email | escape }}",
      properties: {
        subscription_id: "{{ subscription.id }}",
        segment: "VIP members",
        location: "dashboard"
      }
    });
  </script>
{% endif %}

Or track a button click:

<button
  type="button"
  onclick="window.trackKlaviyoCustomerPortalEvent('Clicked VIP add product CTA', {
    email: '{{ subscription.email | escape }}',
    properties: {
      subscription_id: '{{ subscription.id }}',
      segment: 'VIP members',
      location: 'dashboard'
    }
  })"
>
  Add to my next order
</button>

Klaviyo accepts the event request asynchronously. Check the profile or metric in Klaviyo to confirm the event was received.

Caching and freshness

Firmhouse caches Klaviyo profile properties and segment membership for 10 minutes. This keeps Customer Portal pages fast, because Firmhouse does not have to request data from Klaviyo on every page load. This means changes to Klaviyo profile properties or segments can take up to 10 minutes to show up in the Customer Portal. When you are developing Customer Portal templates in preview mode, Klaviyo caching is disabled. Preview mode always requests the latest profile properties and segment membership from Klaviyo so you can test template changes faster. When you update Klaviyo properties that influence segment membership, open the segment in Klaviyo and click Update segment. This makes sure the segment reflects the latest matching profiles before you test the Customer Portal.

Troubleshooting

The OAuth connection option is not visible Ask Firmhouse to enable Native Klaviyo integration for your project. While this feature is in preview, the connection option is only shown for selected projects. The template does not show my Klaviyo content Check that Klaviyo shows OAuth connected in Firmhouse and that the current subscription email address exists as a profile in Klaviyo. Reconnect Klaviyo if Firmhouse reports that new permissions are required. A segment change in Klaviyo is not visible immediately Klaviyo segment membership can take time to update in Klaviyo. If you changed profile properties that affect segment membership, open the segment in Klaviyo and click Update segment. Outside Customer Portal template preview mode, Firmhouse can take up to 10 minutes to show the latest Klaviyo data. The Customer Portal page still loads when Klaviyo is unavailable This is expected. Firmhouse treats Klaviyo profile data as optional personalization data. When the API cannot be reached or returns an error, the Liquid object returns empty properties and segment lists.

Get Started

Get Started on Shopify

Continue your project setup

Customer Portal v2

Self Service Center v1

Manage

Reporting & Metrics

Configure

Billing and Account

Explained

Troubleshooting

Enterprise

Integrate data from Klaviyo

Before you start

Connect Klaviyo with OAuth

Use the Klaviyo profile Liquid object

Show content based on a profile property

Show content based on segment membership

Combine Klaviyo data with Customer Portal actions

Track Customer Portal actions in Klaviyo

Caching and freshness

Troubleshooting

​Before you start

​Connect Klaviyo with OAuth

​Use the Klaviyo profile Liquid object

​Show content based on a profile property

​Show content based on segment membership

​Combine Klaviyo data with Customer Portal actions

​Track Customer Portal actions in Klaviyo

​Caching and freshness

​Troubleshooting

​Related articles

Before you start

Connect Klaviyo with OAuth

Use the Klaviyo profile Liquid object

Show content based on a profile property

Show content based on segment membership

Combine Klaviyo data with Customer Portal actions

Track Customer Portal actions in Klaviyo

Caching and freshness

Troubleshooting

Related articles