Checkout vs Cart Resolution

When a shopper finishes a try-on, the result screen shows one final CTA. data-hemsy-action on the script tag sets the default, and any launcher element can override it with its own data-hemsy-action. It applies to every launch mode, including Instant.

Action	CTA label	What happens
`checkout` (default)	“Go to Checkout”	Hemsy creates or opens a Shopify checkout/cart URL directly.
`cart`	”Go to Cart”	Hemsy posts the selected variants back to your page, calls `window.HemsyEmbedConfig.onProductVariantData(payload)`, and closes the modal.

In the Shopify theme extension, this is the app embed’s “When shoppers finish” setting and each trigger block’s override — no attributes to write. The examples below show the equivalent script install markup. Use cart when your storefront owns cart state and should add the returned variants itself: headless storefronts, Hydrogen, or any site with a custom cart drawer.

<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-selector=".hemsy-launcher"
  data-hemsy-action="cart"
  defer
></script>

To override the action for a single launcher, put data-hemsy-action on the element:

<!-- Page default is checkout; this button hands items to the cart instead -->
<button class="hemsy-launcher" data-hemsy-action="cart">Try before you buy</button>

The legacy script-level data-hemsy-mode="cart" still maps to the cart action for backward compatibility, but prefer data-hemsy-action: data-hemsy-mode should be reserved for "instant". (data-hemsy-mode="checkout" has no effect; checkout is simply the default action.)

Native cart strategy

By default the cart action hands items to your code via onProductVariantData, which means writing a callback. If your storefront is a standard Shopify theme, skip that entirely with data-hemsy-cart-strategy="native":

<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-selector=".hemsy-launcher"
  data-hemsy-action="cart"
  data-hemsy-cart-strategy="native"
  defer
></script>

With the native strategy, when the shopper clicks the final CTA Hemsy:

Adds the returned items to the Shopify cart via the Ajax API (/cart/add.js), converting variant GIDs to numeric IDs and mapping item attributes to line-item properties.
Dispatches cart:refresh, cart:updated, and cart:change events on document with the updated cart, so cart drawers and count bubbles that listen for them update in place.
Closes the modal once the add completes (unless data-hemsy-auto-close="false").

Callbacks still fire if you define them, so you can layer analytics on top. A cart failure never traps the shopper: the modal closes regardless and the error is logged to the console.

The Shopify theme extension uses the native strategy automatically, so merchants who install through the theme editor get a working cart handoff with zero code.

Event callbacks

Callbacks are configured on window.HemsyEmbedConfig (not data attributes). Define it before the embed script loads:

<script>
  window.HemsyEmbedConfig = {
    subdomain: "your-store-subdomain",
    selector: ".hemsy-launcher",
    action: "cart",
    onItemAdded: function (item) {
      // item.variantId - Shopify variant ID (string)
      // item.quantity - always 1
      console.log("Added to bag:", item.variantId);
    },
    onItemRemoved: function (item) {
      console.log("Removed from bag:", item.variantId);
    },
    onProductVariantData: function (payload) {
      // Fired in cart action when the final "Go to Cart" button is clicked.
      console.log("Send these variants to your cart:", payload.items);
    },
  };
</script>

<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-selector=".hemsy-launcher"
  data-hemsy-action="cart"
  defer
></script>

Callback	Payload	Fires when
`onItemAdded`	`{ variantId: string, quantity: number }`	An item is added to the bag inside Hemsy
`onItemRemoved`	`{ variantId: string }`	An item is removed from the bag inside Hemsy
`onProductVariantData`	`{ items: Array<{ variantId: string, quantity: number, attributes?: Array<{ key: string, value: string }> }> }`	`action: "cart"` and the final CTA is clicked

onItemAdded and onItemRemoved fire live as the shopper edits their bag, regardless of action. onProductVariantData is the cart handoff itself: the items array includes any line-item attributes from the original payload (bundle keys and so on), so pass them through to your cart. By default, Hemsy closes the modal after the cart handoff. Set data-hemsy-auto-close="false" on the script tag (or autoClose: false on HemsyEmbedConfig) to keep it open (for example if you show your cart drawer next to the modal).

Hydrogen example

import { useCart } from "@shopify/hydrogen";

function HemsyEmbedSetup() {
  const { linesAdd, linesRemove, lines, cartOpen } = useCart();

  useEffect(() => {
    window.HemsyEmbedConfig = {
      subdomain: "your-store",
      selector: ".hemsy-launcher",
      action: "cart",
      onItemAdded: ({ variantId, quantity }) => {
        linesAdd([
          {
            merchandiseId: `gid://shopify/ProductVariant/${variantId}`,
            quantity,
          },
        ]);
      },
      onItemRemoved: ({ variantId }) => {
        const lineToRemove = lines?.find(
          (line) =>
            line.merchandise.id === `gid://shopify/ProductVariant/${variantId}`,
        );
        if (lineToRemove) {
          linesRemove([lineToRemove.id]);
        }
      },
      onProductVariantData: () => {
        cartOpen();
      },
    };
  }, [linesAdd, linesRemove, lines, cartOpen]);

  return null;
}

variantId is the numeric Shopify variant ID as a string. Convert it to GID format (gid://shopify/ProductVariant/...) for Hydrogen’s cart operations.

Get Started

Installation

Configuration

Native cart strategy

Event callbacks

Hydrogen example

​Native cart strategy

​Event callbacks

​Keeping the modal open

​Hydrogen example

Native cart strategy

Event callbacks

Keeping the modal open

Hydrogen example