Customer Hub JavaScript API reference

You will learn

How to control Customer Hub — or standalone Klaviyo web chat — from your own storefront code using the window.customerHubApi JavaScript API. You’ll open and close the experience, navigate to a specific screen, send a chat message on the shopper’s behalf, and listen for events like add-to-cart.

Before you begin

You’ll need:

• Customer Hub or standalone Klaviyo web chat set up and loaded on your storefront. If you’re on a headless Shopify storefront, follow How to set up Customer Hub with Headless Shopify first. It covers adding the onsite loader that makes this API available.
• Ability to edit and deploy your storefront code.

What the Customer Hub API is

Whenever Customer Hub — or standalone Klaviyo web chat — loads on your storefront, Klaviyo attaches a small JavaScript API to the global window object as window.customerHubApi. You can use it to open, close, and interact with the experience from your own code — for example, from a custom button, banner, or product page.

if (window.customerHubApi) {
  window.customerHubApi.open();
}

Methods

open(route?)

Opens the Customer Hub drawer.

• route (string, optional) — a path to navigate to when opening. If omitted, the Hub opens on whatever screen it was last showing.

// Open the Hub on its current screen (or its initial screen on first open)
window.customerHubApi.open();

// Open the Hub directly to a specific screen
window.customerHubApi.open('/orders');

Available routes

close()

Closes the Customer Hub drawer. The Hub stays on its current screen, so re-opening with open() (no route) returns the customer to where they left off.

window.customerHubApi.close();

sendChatMessage(message)

Opens the Customer Hub on the Chat screen and submits a message on the customer’s behalf, useful for “Chat about this product” or “Get help” buttons. Web chat must be visible to the shopper for the message to be sent.

• message (string) — the message to send.

window.customerHubApi.sendChatMessage('I have a question about my order.');

When login is required: If your store requires customers to log in before chatting (and the AI agent isn’t enabled), the customer is taken to the Chat screen to log in first. The message is saved temporarily and sent automatically once they finish logging in. The saved message expires after about 10 minutes if login isn’t completed.

Chat data limitations

The JavaScript API does not include methods for attaching pre-chat survey responses or retrieving the active conversation ID.

Listen for events

window.customerHubApi.events lets you subscribe to events that happen inside Customer Hub.

addtocart and addtocart_v2

After a successful cart addition from Customer Hub, addtocart fires when your storefront cart display still needs refreshing. Refresh the display without adding the items again. On Shopify, addtocart_v2 fires instead when Klaviyo has already updated the theme’s cart count; the theme’s cart drawer stays closed. Use addtocart_v2 for tracking or other follow-up actions without repeating the cart refresh.

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // The items are already in the cart. Refresh your storefront cart display.
  // event.detail.items is an array of { variantId, quantity }
  console.log('Cart display needs refreshing:', event.detail.items);
});

window.customerHubApi.events.addEventListener('addtocart_v2', (event) => {
  // Klaviyo has already updated the Shopify cart count.
  // Use this listener for tracking or other follow-up actions.
  console.log('Cart display updated:', event.detail.items);
});

Full example

This example enables a “Chat about this product” button and registers cart listeners after the API loads. Replace the body of refreshStorefrontCart with your storefront’s cart-refresh code before deploying. The example logs cart changes until you add that code; it does not refresh the cart display itself. The items are already in the cart, so your refresh code must not add them again.

<button id="ask-about-product" disabled>Ask us about this product</button>

<script>
  (() => {
    const button = document.getElementById('ask-about-product');

    function refreshStorefrontCart(items) {
      // TODO: Replace this log with your storefront's cart-refresh code.
      // Re-fetch and render the existing cart. Do not add these items again.
      console.log('Cart display needs refreshing:', items);
    }

    function initializeCustomerHub() {
      const api = window.customerHubApi;
      if (!api) return;

      button.disabled = false;
      button.addEventListener('click', () => {
        api.sendChatMessage('I have a question about this product.');
      });

      api.events.addEventListener('addtocart', (event) => {
        refreshStorefrontCart(event.detail.items);
      });

      api.events.addEventListener('addtocart_v2', (event) => {
        // The Shopify cart count is already updated. Add tracking here.
        console.log('Cart display updated:', event.detail.items);
      });
    }

    if (window.customerHubApi) {
      initializeCustomerHub();
    } else {
      document.addEventListener(
        'klaviyo-customer-hub-loaded',
        initializeCustomerHub,
        { once: true }
      );
    }
  })();
</script>

Additional resources