Events

Smootify sends an event each time something happens: the cart changes, a product loads, the visitor logs in or changes country. Your script listens and reacts. An event only tells what happened: what your handler returns is ignored. To change what Smootify does, use a filter. Each event, with its payload, is also in the Reference under API.

Listen to an event

window.Smootify = window.Smootify || [];
window.Smootify.push((Smootify) => {
  const stop = Smootify.on("added_to_cart", ({ lines, cart }) => {
    console.log(lines.length, cart.totalQuantity);
  });
  Smootify.once("initiate_checkout", ({ cart }) => console.log(cart.id));
  // later: stop();
});

• The name can be written with or without its smootify: prefix: "cart_updated" or "smootify:cart_updated".
• on and once return a function that stops listening. once stops by itself after the first event.
• { replay: true }, as the third argument of on, also calls the handler at once with the last payload of an event that already happened.
• Every event is also a DOM event, with the payload in event.detail: document.addEventListener("smootify:cart_updated", (event) => console.log(event.detail)). Four of them are sent on an element instead of document: see Events sent on an element.
• Listening to consent_changed is enough to make Smootify load Shopify’s consent script.

Add your listeners in a push function: they then get every event from the first product_loaded and cart_updated on. See Run your scripts with Smootify.

Which event for what

• Start your code once everything is loaded: loaded, with { replay: true }.
• Keep your own cart counter or total in sync: cart_updated. It also fires when the cart first loads.
• Track an addition: added_to_cart. For the checkout: initiate_checkout.
• React to the chosen variant: variant_changed.
• Know whether the visitor is logged in: user_auth_change with { replay: true }, or await Smootify.getCustomer().
• Start analytics after consent: consent_changed.

The events

Loading and products

Smootify.on("loaded",
  () => { /* … */ })

Smootify.on("product_loaded",
  ({ product, id }) => { /* … */ })

Smootify.on("product_expired_load",
  ({ product, id }) => { /* … */ })

Smootify.on("loadedAdditionalVariants",
  ({ product }) => { /* … */ })

Smootify.on("variant_changed",
  ({ element, product, variant }) => { /* … */ })

document.querySelector("smootify-add-to-cart")
  .addEventListener("smootify:changed_option",
    (event) => { /* event.detail */ })
// detail: { optionChangedIndex, selectedValue, variant }

In product_loaded, product is null when Shopify does not return the product: it is not published to the store’s sales channel, or not sold in the visitor’s market. In variant_changed, element is the smootify-product on the page and variant is undefined for a combination that does not exist.

Cart

Smootify.on("cart_updated",
  cart => { /* … */ })

Smootify.on("added_to_cart",
  ({ lines, cart, goToCheckout }) => { /* … */ })

Smootify.on("removed_from_cart",
  lineIds => { /* … */ })

Smootify.on("errors",
  errors => { /* … */ })

Smootify.on("initiate_checkout",
  ({ cart }) => { /* … */ })

Smootify.on("cart_opened",
  ({ element }) => { /* … */ })

cart_opened and cart_closed fire for every kind of mini cart (dialog, details, Webflow Dropdown, popover or your own trigger), never for a cart page. element is the smootify-cart.

Customer, market and consent

Smootify.on("user_auth_change",
  customer => { /* … */ })

Smootify.on("changed_country",
  ({ country, oldCountry }) => { /* … */ })

Smootify.on("consent_changed",
  consent => { /* … */ })

Smootify.on("created_address",
  ({ address }) => { /* … */ })

The first user_auth_change goes out before the push functions run. Listen with { replay: true } to get it.

Wishlist

Smootify.on("wishlist:changed_product_state",
  ({ node, product, active }) => { /* … */ })

Smootify.on("wishlist:changed_product",
  ({ node, product }) => { /* … */ })

Smootify.on("wishlist:changed_variant_state",
  ({ node, variant, active }) => { /* … */ })

Smootify.on("wishlist:changed_variant",
  ({ node, variant }) => { /* … */ })

node is the wishlist-toggle. More in Wishlist.

Search and discovery

document.querySelector("smootify-search-discovery")
  .addEventListener("smootify:filter_initial_change",
    (event) => { /* event.detail */ })
// detail: { name, value }

document.querySelector("smootify-search-discovery")
  .addEventListener("smootify:filter_changed",
    (event) => { /* event.detail */ })
// detail: { name, value }

document.querySelector("smootify-search-discovery")
  .addEventListener("smootify:sort_changed",
    (event) => { /* event.detail */ })
// detail: { name: "sort", value }

These three are sent on an element: see below.

Events sent on an element

Four events are not sent on document, and do not bubble up to it:

• changed_option is sent on the smootify-add-to-cart form around the picker, or on the picker when it is outside the form;
• filter_initial_change, filter_changed and sort_changed are sent on the smootify-search-discovery block, or on the smootify-search-page block.

Where you listen decides whether your handler runs:

The two ways that work, in code:

document.addEventListener(
  "smootify:changed_option",
  (event) => console.log(event.detail.optionChangedIndex, event.detail.selectedValue),
  true,
);

document
  .querySelector("smootify-search-discovery")
  ?.addEventListener("smootify:filter_changed", (event) => console.log(event.detail.name, event.detail.value));

To react to a new variant, variant_changed is simpler: it is sent on document and carries the product element.

Other DOM events

Smootify also sends a few DOM events kept from 1.x. They are not in smootify.d.ts:

• productLoaded and changeVariant on each smootify-product element, with the product or the variant in event.detail. They do not bubble: listen on the element. changeVariant also fires at the first render.
• changePlan on each smootify-product element, when the visitor picks a selling plan or goes back to the one-time purchase. event.detail has plan (null for the one-time purchase) and variant. It does not bubble: listen on the element.
• addon:state_change on document and on the smootify-add-to-cart form, each time an add-on is picked or dropped. event.detail has wrapper (the add-on element), product, variant and included.
• variantsRendered on document.body, each time a variant card (smootify-variant) is filled.
• smootify:productImagesModuleLoaded on document, each time a deprecated product="images" element draws its images. The product="gallery" element does not send it. It does not mean every image has finished downloading.
• smootify:magic_box_change on document.body, once the box has loaded and after each change: see Example: a Magic Box title that follows its contents.
• smootify:price_render on document, each time a smootify-price writes a new amount. event.detail.element is the price element.
• smootify.devMetafield and smootify.renderedMetafields on document, for metafields: see Render a metafield yourself.

Example: a Magic Box title that follows its contents

smootify:magic_box_change carries element (the smootify-magic-box), currentQuantity (how many products the box holds) and cartItems, one { lineItem, variant } per product. The box element has two methods: modifyBoxTitle(title) and modifyBoxImage(url), which accepts only an image served by Shopify’s CDN (upload it under Content > Files). The new title and image are the ones the box line takes in the cart and at checkout.

document.body.addEventListener("smootify:magic_box_change", (event) => {
  const { element, currentQuantity } = event.detail;
  element.modifyBoxTitle(`Box of ${currentQuantity} wines`);
  element.modifyBoxImage(
    currentQuantity > 3 ? "https://cdn.shopify.com/…/box-large.jpg" : "https://cdn.shopify.com/…/box-small.jpg",
  );
});

Add the listener before the box loads, in the page’s head code, so it also gets the first event.

Example: the store credit a cart earns

When a Shopify Flow workflow gives store credit on paid orders, like Store credit on a paid order (5% of the subtotal from 50 up), the cart can say what this order will earn. Smootify has no attribute for it, because the rule is yours: the percentage, the minimum and whether to show it at all. A few lines on cart_updated do it.

Put the message next to the cart’s subtotal, outside the line template, and hide it in Webflow:

<p data-credit-estimate hidden>This order earns you <span data-credit-amount></span> of store credit.</p>

Then add the script, with the same numbers as your workflow:

window.Smootify = window.Smootify || [];
window.Smootify.push((Smootify) => {
  const RATE = 0.05; // the share your workflow credits
  const MINIMUM = 50; // its minimum subtotal
  const SHOP_CURRENCY = "EUR"; // the currency of that minimum

  Smootify.on("cart_updated", (cart) => {
    const { amount, currencyCode } = cart.cost.subtotalAmount;
    const subtotal = Number(amount);
    const earns = currencyCode === SHOP_CURRENCY && subtotal >= MINIMUM;
    document.querySelectorAll("[data-credit-estimate]").forEach((message) => {
      message.hidden = !earns;
      const value = message.querySelector("[data-credit-amount]");
      if (earns && value) value.textContent = Smootify.formatMoney((subtotal * RATE).toFixed(2));
    });
  }, { replay: true });
});

• It is an estimate. The credit is what the workflow gives when the order is paid. Change the numbers in both places, or the cart promises what the workflow does not give.
• One currency. The minimum is in the shop’s currency, so the message shows only when the visitor’s cart is in that currency. In other markets it stays hidden.
• { replay: true } shows it at once for the cart that already loaded.

Where people get stuck

Coming from 1.x

The names and the payloads of the events are the same as in 1.x, with these changes:

• Wishlist events are renamed smootify:wishlist:…, like every other event. The 1.x names (smootify_wishlist:changed_product, changed_product_state, changed_variant, changed_variant_state) are still sent, with the same payload, until 3.0.
• New in 2.0: cart_opened, cart_closed, consent_changed and variant_changed.
• Now sent: created_address and the two wishlist:changed_variant events, which 1.x declared and never sent.
• One event per thing that happened. product_loaded goes out once per product, changed_option only when the visitor picks a value, sort_changed not for a selected-value preselection, and smootify:price_render only when the amount changes. A script that counted events to detect the end of loading should listen to loaded.
• smootify:color_patterns is no longer sent: 2.0 does not load the shop’s colour patterns.
• Smootify.on and once are new: in 1.x, scripts used document.addEventListener, which still works.