How to set up Customer Hub with Headless Shopify

Connect Klaviyo Customer Hub to your headless Shopify storefront. Enable login, surface widgets (Favorites, FAQs), and power Active/Recently Viewed product experiences to lift engagement and conversion.

You will learn

You’ll connect Customer Hub to a headless Shopify storefront, choose a login method, and publish the Hub so shoppers can access it site‐wide.

Before you begin

Prerequisites

• A headless Shopify storefront with access to the Storefront API (Public access token / Storefront API public key in Shopify’s Headless Admin).
• Your Klaviyo company ID (used by the onsite JavaScript loader).
• Decision on shopper login: Shopify Customer Account API or Klaviyo One Time Password (OTP).
  • If using existing accounts, have your storefront’s Login, Logout, and (optional) Manage account and Manage addresses routes ready.
• Ability to edit your storefront code and deploy changes.
• An account role with permission to edit Customer Hub, such as Owner or Admin. For a custom role, include Customer Hub view and edit permissions.
• A Customer Hub trial or a plan that includes Favorites and FAQs, if you want to use these features.

Overview

Customer Hub is a site‐wide overlay that gives shoppers faster access to account actions and helpful shopping tools. For headless Shopify, you connect Klaviyo’s onsite script, choose a login method (Shopify Customer Account API or Klaviyo OTP), and optionally add:

• Active Product: shows the product a shopper is viewing inside the Hub.
• Recently Viewed: lists recently viewed products using Klaviyo’s tracking.
• Favorites and FAQs widgets: render on product detail pages (PDPs) and inside the Hub.

Use Customer Hub when you want an on‐page assistance layer that drives product discovery and faster checkout, improving conversion and lifetime value.

Setup

1. Configure Customer Hub settings

First, follow Getting started with Customer Hub and complete the onboarding wizard. Keep Customer Hub hidden until your headless setup is ready. Then go to Customer Hub > Settings and find Headless Shopify configuration.

Toggle on Headless Shopify configuration and paste your Shopify public access token into Storefront API public key.

Under Shopper login, select Shopify Customer Account API to use your existing Shopify login, or Klaviyo One Time Password (OTP) for a login that works only with Klaviyo.

If you select Shopify Customer Account API, enter your storefront’s Login route and Logout route. Manage account route and Manage addresses route are optional. These routes redirect shoppers between the Hub and your site.

If you select Klaviyo One Time Password (OTP), enter Store display name and Reply to email. The reply email cannot use a gmail.com or klaviyo.com address.

Click Save to save your settings. To check the Hub’s publishing status, click Open editor. Keep the status Hidden until you finish the storefront setup and testing below.

2. Load the Customer Hub JavaScript (developer instructions)

Tip: If you already run Klaviyo onsite features, you may have a loader in place. Confirm before adding a second script.

Create /public/customerHub.js (or equivalent) with the following loader (replace COMPANY_ID with your Klaviyo public API key, also known as your Company ID):

// customerHub.js
// TODO: Configuration
const COMPANY_ID = '';
const script = document.createElement('script');
script.src = `https://static.klaviyo.com/onsite/js/${COMPANY_ID}/klaviyo.js`;
script.async = true;
script.onload = () => { console.log('Klaviyo JS script loaded successfully'); };
script.onerror = () => { console.error('Failed to load Klaviyo JS script'); };
document.body.appendChild(script);

In your root layout (e.g., root.tsx), include the loader so the onsite script loads on every page. Look for the console message “Klaviyo JS script loaded successfully.”

// root.tsx
return (
  <html>
    <body>
      <script src="/customerHub.js" defer></script>
    </body>
  </html>
)

After the Hub finishes loading, window.customerHubApi becomes available. The loader’s success message confirms that the script loaded; wait for the Hub API before calling hydrateProduct as shown below.

3. Show the active product in Customer Hub

Add the following script to your product page HTML, replacing your-product-handle with the current Shopify product handle. If your storefront uses React or another framework with client-side navigation, run the hydration call from that framework’s page lifecycle whenever the product changes.

<!-- Product page HTML -->
<script type="text/javascript">
  (function() {
    function waitForCustomerHubApi() {
      return new Promise((resolve) => {
        const check = () => {
          if (window.customerHubApi && window.customerHubApi.hydrateProduct) {
            resolve();
          } else {
            requestAnimationFrame(check);
          }
        };
        check();
      });
    }
    waitForCustomerHubApi().then(() => {
      window.customerHubApi.hydrateProduct("your-product-handle");
    });
  })();
</script>

On desktop, the Hub can display the current product card in the Chat tab when web chat is enabled. This card is not shown on mobile.

4. Enable recently viewed products in Customer Hub

Implement Viewed Product tracking on your product pages so you can use this metric in Klaviyo. Also call trackViewedItem to store recently viewed products in the shopper’s browser for the Hub. Follow the tracking examples in Integrate an ecommerce platform without a pre-built Klaviyo integration.

5. Enable account link takeover

When Customer Hub is Live, it can replace account links ending in /account or /account/login so they open the Hub. To open the Hub from a custom account icon, set the link to #k-hub. Add data-k-hub-ignore to an account link if it should keep opening your storefront’s account page.

6. Connect Shopify Customer Account API authentication (recommended)

Complete this step only if you selected Shopify Customer Account API under Shopper login. If you selected Klaviyo One Time Password (OTP), skip to step 7.

Add a server route at /api/authenticateCustomerHub that accepts POST requests and passes the logged-in shopper’s access token to Klaviyo. Set COMPANY_ID in the example to your Klaviyo company ID.

The following example uses Shopify’s Hydrogen framework. Adapt the server route to your framework if you use a different storefront.

// ./app/routes/api.authenticateCustomerHub.js
// TODO: Configuration
const COMPANY_ID = '';
export async function action({context}) {
  // Pull the Customer Account API Client from your storefront's context
  const {customerAccount} = context;
  try {
    // Get the access token for the current customer
    const accessToken = await customerAccount.getAccessToken();
    if (!accessToken) {
      return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
    }
    // Send the access token to the Customer Hub API
    const response = await fetch(
      'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          access_token: accessToken,
          company_id: COMPANY_ID,
        }),
      },
    );
    const responseData = await response.text();
    // Return the actual response from Customer Hub with the same status code
    return new Response(responseData, {
      status: response.status,
      headers: {
        'Content-Type':
          response.headers.get('content-type') || 'application/json',
      },
    });
  } catch (error) {
    return new Response(null, {status: 500});
  }
}

Once this route and the storefront routes in Klaviyo’s settings are configured, Customer Hub can connect to your existing customer account login.

7. Add the Favorites widget (recommended)

Favorites and FAQs can appear inside the Customer Hub drawer. You can also add them to product detail pages so shoppers can save products and find answers while browsing.

Enable Favorites in the Hub editor first. Then go to Customer Hub > Design, select Favorites, and choose which shoppers can see the onsite widget. Click Publish to save your widget settings, then add the following container to your product page. Replace the example Shopify product ID with the current product’s ID.

// products.tsx
// Example identifiers:
//   id: gid://shopify/Product/12345
//   data-product-id: 12345
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();

return (
  <div
    className="kl-hub-favorites-slot"
    data-product-id={productId}
  />
)

Once Customer Hub is Live and the widget is visible to the shopper, they can click Add to favorites on a product page. Their saved products appear in the Hub’s Favorites experience.

8. Add FAQ blocks (recommended)

Create your FAQ blocks in Klaviyo. In Customer Hub > Design, select FAQ, choose the questions to display on product pages, and configure the onsite visibility and design. Click Publish to save your settings before adding the container below.

Add this container to your product page with the current Shopify product ID. The same selected FAQs appear across product pages; the product ID does not select different questions for each product.

// products.tsx
// Example:
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();

return (
  <div className="klaviyo-faqs-slot" data-product-id={productId} />
)

The selected FAQ buttons appear on product pages according to your visibility settings. Clicking a question opens its answer in Customer Hub.

9. Test and set Customer Hub live

Test your storefront code in staging before deploying it to production. Automatic account link takeover and the onsite Favorites widget require Live, so include them in your final live checks.

1. When you are ready to publish, go to Customer Hub > Settings and click Open editor.
2. Save any pending Hub design changes. Then select Live in the status dropdown, or click Go live when the Hub is hidden and has no unsaved changes.
3. Wait for the confirmation that Customer Hub is live. On your production storefront, check login and logout, the account icon, the desktop Chat product card if enabled, recently viewed products, and any Favorites or FAQ widgets you added.

Best practices

• Publish to production only after testing to help avoid support issues. Keep the production Hub Hidden until the setup is ready, then set it Live from the Hub editor.
• Hydrate the active product on PDPs to keep product context available in the Hub and help shoppers add it to their cart. Monitor conversion rate and revenue per recipient (RPR) to assess the effect.
• Implement product tracking early to populate recently viewed products and support browse-based flows. Monitor engagement and revenue from browse recovery.
• Add Favorites to give shoppers an easy way to save a shortlist. Monitor repeat visits and add-to-cart activity.
• Use FAQs to answer questions about shipping, materials, or returns while shoppers browse. Monitor drop-off and conversion rate.
• Use server-side authentication with Shopify Customer Account API when available to maintain continuity for logged-in shoppers and help reduce login-related support requests.

Measuring success

Use Analytics > Metrics to monitor Viewed Product activity. Review downstream performance in your flows and campaigns. Use your ecommerce revenue dashboards to track conversion and average order value (AOV) changes after enabling Customer Hub.

Watch conversion rate from product pages, add-to-cart rate, sessions with Hub opens (if instrumented), revenue per recipient (RPR), and browse-driven revenue tied to Viewed Product events.

Quick checks

• For low recently viewed activity, verify product tracking and check that Viewed Product events are attributed to profiles. Also check browser-based recently viewed tracking.
• For low add-to-cart activity from the Hub, check that active product hydration runs on each PDP and that variants and prices are correct.
• For few Favorites adds, place the Favorites slot near the main product page calls to action and confirm that data-product-id matches the product.

Troubleshooting

Symptom: Customer Hub does not appear on the site.

Likely cause: Script not loading or Hub is Hidden.

Fix: Confirm customerHub.js loads, the company ID is set, and Customer Hub is Live. To change its status, go to Customer Hub > Settings > Open editor and use the status dropdown.

Symptom: Console shows “Failed to load Klaviyo JS script.”

Likely cause: Incorrect script URL or missing company ID.

Fix: Verify https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js and that COMPANY_ID is populated.

Symptom: Active Product card does not show in the Hub on PDPs.

Likely cause: The hydration call is missing, the product handle is wrong, or you are checking the Chat product card on mobile.

Fix: On desktop, open Chat with web chat enabled. Ensure the wait loop runs and call window.customerHubApi.hydrateProduct("<handle>") with the correct product handle.

Symptom: Recently viewed section is empty.

Likely cause: Missing or incomplete product tracking.

Fix: Add Viewed Product event tracking and trackViewedItem browser tracking. Verify events on a recognized profile and check recently viewed products in the same browser.

Symptom: Favorites or FAQ widgets don’t render on PDP.

Likely cause: A missing container, incorrect product ID, hidden widget, or a plan that does not include the feature.

Fix: Add <div class="kl-hub-favorites-slot" data-product-id="..."></div> or <div class="klaviyo-faqs-slot" data-product-id="..."></div> with the correct product ID. Confirm feature access and visibility in Klaviyo, and select FAQs for product pages. Customer Hub must also be Live for the Favorites widget to appear.

Symptom: Clicking the account icon doesn’t open the Hub.

Likely cause: The account link does not match a supported account URL, is excluded from takeover, or Customer Hub is hidden.

Fix: Set Customer Hub to Live, use an account link ending in /account or /account/login, or set href="#k-hub". Remove data-k-hub-ignore only from links that should open the Hub.

Symptom: With Shopify Customer Account API selected, shoppers are not recognized as logged in inside the Hub.

Likely cause: Missing /api/authenticateCustomerHub route or failing API request.

Fix: Implement the Hydrogen example (or your framework equivalent), send access_token and company_id to Klaviyo’s login endpoint, and return the response.

FAQ

Q: Do I have to use Shopify Customer Account API for login?

A: No. You can use Klaviyo One Time Password (OTP) instead. If you already use Shopify accounts, connect via the Shopify Customer Account API for a seamless experience.

Q: Which storefront routes do I need to provide?

A: For Shopify Customer Account API, provide Login route and Logout route. Manage account route and Manage addresses route are optional for deeper linking.

Q: Where do I find the Storefront API public key?

A: Use the public access token for your storefront in Shopify’s Headless channel. Follow Shopify’s Storefront API setup guide, then enter the public token in Klaviyo’s Storefront API public key field.

Q: Can Customer Hub take over my account icon?

A: Yes. When Customer Hub is Live, links ending in /account or /account/login can open the Hub automatically. You can also point your account link to #k-hub.

Q: Is Shopify Hydrogen required?

A: No. The authentication example uses Hydrogen, but any framework can implement a server route at /api/authenticateCustomerHub that posts the access token and company_id to Klaviyo.

Q: Can Favorites and FAQs live on PDPs and inside the Hub?

A: Yes. Configure Favorites and FAQs in Klaviyo, then add their container divs to your product pages. Their visibility in the Hub and on product pages follows the settings you choose.