Events

The widget exposes an event-driven API. Attach listeners in your application and keep business logic there.

Register and remove listeners

const onAddToCart = (data: { products: Array<{ productId: string; variantId?: string }> }) => {
  console.log("add_to_cart", data.products);
};

widget.on("add_to_cart", onAddToCart);

// Later, cleanup:
widget.off("add_to_cart", onAddToCart);

Event reference

ready

Fired when the widget is ready to use.

widget.on("ready", () => {
  console.log("Widget ready");
});

add_to_cart

Fired when the widget requests adding products to cart.

Payload shape:

type AddToCartEvent = {
  products: Array<{
    productId: string;
    variantId?: string;
  }>;
};

Example:

widget.on("add_to_cart", async (data) => {
  for (const product of data.products) {
    // Resolve variant if needed, then call your cart API/action
    await addToCartInYourApp(product);
  }
});

send_to_checkout

Fired when user should be redirected to checkout.

widget.on("send_to_checkout", () => {
  window.location.href = "/checkout";
});

error

Fired when the widget reports an error.

widget.on("error", (error: Error) => {
  console.error("Sophi error", error.message);
});