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 set up and loaded on your storefront. If you’re on a headless or custom 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 default screen
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.

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

Listen for events

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

addtocart

Fires when a customer adds a product to their cart from within the Hub. Use it to keep your storefront cart in sync.

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // event.detail.items is an array of { variantId, quantity }
  event.detail.items.forEach((item) => {
    console.log('Added to cart:', item.variantId, 'x', item.quantity);
  });
});

Full example

A “Chat about this product” button that opens the Hub and submits a message, plus a listener that syncs the storefront cart when a shopper adds an item from the Hub:

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

<script>
  document
    .getElementById('ask-about-product')
    .addEventListener('click', () => {
      if (window.customerHubApi) {
        window.customerHubApi.sendChatMessage(
          'I have a question about this product.'
        );
      }
    });

  // Sync the storefront cart when a customer adds an item from the Hub
  if (window.customerHubApi) {
    window.customerHubApi.events.addEventListener('addtocart', (event) => {
      refreshStorefrontCart(event.detail.items);
    });
  }
</script>

Additional resources