Use Klaviyo segments in the Customer Portal

Use subscription.segments to personalize Customer Portal v2 for the logged-in customer’s subscription. For example, show a VIP message or an add-product action to customers who belong to a Klaviyo segment synchronized into Firmhouse.

Before you start

You need Customer Portal v2 enabled and access to Customer Portal > Templates.

Install the Firmhouse Klaviyo app. In Apps > Klaviyo > Configure, open Configuration and check that Account connection shows the expected connected account. If Connect Klaviyo is missing, ask Firmhouse to enable the Native Klaviyo integration preview.
Create the audience you want to use in Klaviyo.
Open Klaviyo segments in Firmhouse and wait for automatic synchronization to import the segment list and memberships. There is no per-segment switch or Sync all control.
Click Refresh for the segment you want to use and wait for Last synced to update. Click the subscription count to check that your test subscription is included.

Firmhouse matches Klaviyo profiles to completed subscriptions by email address. One profile can match multiple subscriptions, so the Klaviyo profile count and Firmhouse subscription count can differ. Segments with more than 100,000 Klaviyo profiles are not synchronized into Firmhouse. If a segment shows Not synced because of this limit, its memberships are unavailable in subscription.segments until its profile count falls to 100,000 or fewer and the next synchronization completes.

Segment fields and types

subscription.segments is a list of subscription_segment objects representing the subscription’s enabled memberships stored in Firmhouse. Each object exposes:

Field	Type	Meaning
`id`	Number	The Firmhouse subscription segment ID.
`name`	String	The segment name synchronized into Firmhouse.
`source`	String	The segment’s source, such as `"klaviyo"`.
`external_id`	String	The segment ID at its source. For Klaviyo segments, this is the Klaviyo segment ID.

Filter by source when targeting Klaviyo membership. Use external_id for conditions that should keep working when a segment is renamed. The id field identifies the Firmhouse record and is different from the Klaviyo ID.

Show content for a Klaviyo segment

Replace SEGMENT_ID_FROM_KLAVIYO with the ID displayed beside the segment in Klaviyo segments:

{% assign is_vip_member = false %}
{% for segment in subscription.segments %}
  {% if segment.source == "klaviyo" and segment.external_id == "SEGMENT_ID_FROM_KLAVIYO" %}
    {% assign is_vip_member = true %}
    {% break %}
  {% endif %}
{% endfor %}

{% if is_vip_member %}
  <p>Thanks for being a VIP customer.</p>
{% endif %}

You can also match a segment by name. Update this condition if you rename the segment:

{% for segment in subscription.segments %}
  {% if segment.source == "klaviyo" and segment.name == "VIP members" %}
    <p>Here is an extra recommendation for your next order.</p>
    {% break %}
  {% endif %}
{% endfor %}

Show a Customer Portal action

Combine the membership check with a Customer Portal component:

{% for segment in subscription.segments %}
  {% if segment.source == "klaviyo" and segment.external_id == "SEGMENT_ID_FROM_KLAVIYO" %}
    <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>
    {% break %}
  {% endif %}
{% endfor %}

Synchronization and preview

Portal pages read stored membership from Firmhouse. They do not request membership from Klaviyo on each page load, and segment membership does not use a 10-minute cache. Scheduled synchronization runs hourly. Allow time for Klaviyo to update its audience and for Firmhouse to finish synchronizing it. For testing, check the customer’s membership in Klaviyo, then use Refresh in Firmhouse and wait for Last synced to update before reloading the portal or template preview. Template preview uses the same synchronized memberships. Opening preview does not refresh them. Eligible segments synchronize automatically while the native integration is enabled and connected. Disconnecting the Klaviyo account removes synchronized Klaviyo segments. A segment deleted in Klaviyo is removed from Firmhouse on a subsequent synchronization.

Troubleshooting

The template does not show the expected content Check that the app is enabled and connected, the segment has finished synchronizing, and it includes the subscription you are previewing. Confirm the subscription completed signup and its email matches a profile in the Klaviyo segment. Compare the template’s source and external_id with the segment in Firmhouse. A segment change is not visible in preview Check that Klaviyo has updated its membership, then click Refresh in Firmhouse. Wait for Last synced to update and reload preview. Changing a Klaviyo profile property alone does not immediately update membership stored in Firmhouse. Klaviyo is temporarily unavailable subscription.segments reads Firmhouse records, so portal rendering does not depend on a live Klaviyo API request. Existing stored membership can remain visible while synchronization is failing. Check the connection and synchronization status before relying on membership being current.

Get Started

Get Started on Shopify

Continue your project setup

Customer Portal v2

Self Service Center v1

Manage

Reporting & Metrics

Configure

Integrations & API

Billing and Account

Explained

Troubleshooting

Enterprise

Use Klaviyo segments in the Customer Portal

Before you start

Segment fields and types

Show content for a Klaviyo segment

Show a Customer Portal action

Synchronization and preview

Troubleshooting

​Before you start

​Segment fields and types

​Show content for a Klaviyo segment

​Show a Customer Portal action

​Synchronization and preview

​Troubleshooting

​Related articles

Before you start

Segment fields and types

Show content for a Klaviyo segment

Show a Customer Portal action

Synchronization and preview

Troubleshooting

Related articles