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.

Works with web chat too. The same API is available whether you run the full Customer Hub or just standalone Klaviyo web chat. Web chat supports fewer features than Customer Hub, so some of the screens and events documented below aren’t available there. As a rule, which screens are available depends on the features enabled for your store — navigating to one that isn’t enabled falls back to the Home screen.

Tip: Customer Hub loads asynchronously. Always check that window.customerHubApi exists before calling a method, so your code doesn’t error if it runs before the Hub is ready.

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

Route	Screen
/	Home
/chat	Chat
/orders	Orders
/cart	Cart
/faq	FAQ
/profile	Profile
/coupons	Coupons
/rewards	Rewards / Loyalty
/wishlist (or /favorites)	Wishlist
/recently-viewed	Recently viewed products
/recommended-products	Recommended products

Which screens are available depends on the features enabled for your store. Navigating to a screen that isn’t enabled falls back to the Home screen.

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);
  });
});

Property	Type	Description
event.detail.type	'addtocart'	The event type.
event.detail.items	Array<{ variantId: string; quantity: number }>	The product variants added to cart.

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>