JavaScript API

The methods, events and filters of window.Smootify.

v2.0 beta

Open .md

On this page

At a glance
Methods
Events
Filters

At a glance

window.Smootify

Methods: ask and act

Use it to: Read the cart, the products, the customer or the market; add to the cart; open the mini cart.
For example: getCart(), addToCart(), getCustomer()
Good to know: Call them from a push function. Most return a Promise.

Smootify.on

Events: react to what happened

Use it to: Keep your own counter in sync, track additions, start analytics after consent.
For example: cart_updated, added_to_cart, consent_changed
Good to know: What the handler returns is ignored. once stops after the first event.

Smootify.addFilter

Filters: change it before it happens

Use it to: Check or enrich the lines added to the cart, change the checkout address or a draft order, choose the metafields the page asks for.
For example: add_to_cart_lines, checkout_url
Good to know: Answer the value changed, nothing to keep it, or false to stop.

/cart.js

AJAX API: apps written for Shopify themes

Use it to: Run an app's snippet as it is: Smootify answers the theme endpoints on the page.
For example: /cart.js, /cart/add.js, /products/{handle}.js
Good to know: Same cart as the page. Start the snippet with type="smootify-load".

Methods

Method	What it does
`Smootify.push()`	runs each function once Smootify knows the visitor and the market, before it loads products and cart, so listeners get every event and filters apply from the first request; right away later on. One that throws does not stop the others.	new in 2.0
`Smootify.on()`	listens to an event; `replay` also calls the handler with the last payload of one that already happened. Returns the unsubscribe.	new in 2.0
`Smootify.once()`	—	new in 2.0
`Smootify.addFilter()`	adds a filter after the ones added before it; returns its removal	new in 2.0
`Smootify.getCart()`	—	—
`Smootify.getCartID()`	—	—
`Smootify.addToCart()`	adds lines (through the `add_to_cart_lines` filters): resolves with the cart, or with Shopify’s errors	—
`Smootify.addBoxToCart()`	adds lines as one Magic Box, with its title, image and discount percentage (`___dp`)	—
`Smootify.updateCartLines()`	rejects with Shopify’s errors	—
`Smootify.removeCartLines()`	`dispatchEvents: false` changes the cart without events or re-render (1.x)	—
`Smootify.clearCart()`	—	—
`Smootify.reloadCart()`	asks Shopify for the cart again	—
`Smootify.applyCouponCode()`	resolves with the cart, or with Shopify’s errors	—
`Smootify.removeCouponCode()`	rejects with Shopify’s errors	new in 2.0
`Smootify.applyGiftCard()`	resolves with the cart, or with Shopify’s errors	—
`Smootify.removeGiftCard()`	the id is the applied gift card’s (`cart.appliedGiftCards[].id`); rejects with Shopify’s errors	new in 2.0
`Smootify.updateCartNote()`	—	new in 2.0
`Smootify.updateCartAttributes()`	—	new in 2.0
`Smootify.checkout()`	goes to checkout, as the cart’s checkout button, after the `checkout_url` filters; rejects with the errors	new in 2.0
`Smootify.openCart()`	opens the page’s mini cart (not a cart page)	new in 2.0
`Smootify.closeCart()`	—	new in 2.0
`Smootify.getCartAsDraftOrderData()`	the cart as a draft order input (Draft Orders)	—
`Smootify.getProductsById()`	the products by id that Shopify knows in the current market	—
`Smootify.getProductByHandle()`	—	new in 2.0
`Smootify.selectVariant()`	selects a variant (its number or gid) of a `smootify-product` of the page: the element, or one inside it; false when the product has no such variant	new in 2.0
`Smootify.toast()`	shows the page’s `[toast="<name>"]` (in `smootify-toasts`) with `items` written into its `[toast-item]` children, as `Smootify.toast("added-to-cart", { title: "Gift wrap" })`; false when the page has no such template	new in 2.0
`Smootify.isLoggedIn()`	—	new in 2.0
`Smootify.getCustomer()`	the customer (null for a guest) once the session is known	new in 2.0
`Smootify.passwordlessLogin()`	starts the login of Shopify’s customer accounts	—
`Smootify.logout()`	ends the session, and Shopify’s too	new in 2.0
`Smootify.getNewCustomerAccessToken()`	the Customer Account API token of the session ("" for a guest)	—
`Smootify.queryCustomer()`	a Customer Account API query on the customer: `fields` is the selection inside `customer { … }`	—
`Smootify.setCustomerMetafields()`	—	—
`Smootify.getLocalization()`	country, currency, language and where the store sells, once known	new in 2.0
`Smootify.changeCountryByIsoCode()`	true when the country changed (the page follows it)	—
`Smootify.changeMarketLanguage()`	—	—
`Smootify.formatMoney()`	an amount in the store’s money format; `forceNoHtml` and `forceNoTaxes` are accepted and ignored (1.x)	—
`Smootify.getConsent()`	the visitor’s consent; loads Shopify’s Customer Privacy script when the page has not yet	new in 2.0
`Smootify.setConsent()`	—	new in 2.0
`Smootify.enableAnalytics()`	1.x: Shopify’s analytics with (`true`) or without the visitor’s consent	—
`Smootify.query()`	a Storefront API query in the current market: resolves with `data`, rejects with the GraphQL errors	—

Events

Event	When
`smootify:loaded`	Smootify is loaded: the API answers, the session, the market and the cart are known (once per page)	—
`smootify:product_loaded`	a product was loaded; null for an id that is not published on the Headless channel or in the market	—
`smootify:product_expired_load`	a product shown from the cache changed on Shopify: this is the fresh one	—
`smootify:loadedAdditionalVariants`	the product page’s product with every variant, when it has more than 250	—
`smootify:added_to_cart`	lines were added, after the cart came back: once per add to cart, a product with its add-ons included (the main line first); when the add-ons fail, the main line that went in alone	—
`smootify:removed_from_cart`	the ids of the removed lines	—
`smootify:cart_updated`	every change of the cart, the first load included	—
`smootify:errors`	Shopify’s errors of a cart operation, or the error a filter threw	—
`smootify:initiate_checkout`	the visitor goes to checkout	—
`smootify:user_auth_change`	the session is known or changed: the customer, null for a guest	—
`smootify:filter_initial_change`	a filter Search & Discovery applied from `selected-value` or the url, before the first search	—
`smootify:filter_changed`	the visitor changed a filter (`name: "query"` for the search text)	—
`smootify:sort_changed`	—	—
`smootify:changed_option`	the visitor changed an option of a product (not at the first render)	—
`smootify:changed_country`	—	—
`smootify:created_address`	a `create-address` form saved an address	—
`smootify:wishlist:changed_variant`	`wishlist-toggle[data-use-variants]`: the toggle follows another variant	—
`smootify:wishlist:changed_variant_state`	—	—
`smootify:wishlist:changed_product`	—	—
`smootify:wishlist:changed_product_state`	the visitor added (`active`) or removed a product	—
`smootify:color_patterns`	1.x only: 2.0 has no global color patterns and never dispatches it	never dispatched in 2.0
`smootify:cart_opened`	a mini cart (dialog, details, dropdown, popover, custom) opened	new in 2.0
`smootify:cart_closed`	—	new in 2.0
`smootify:consent_changed`	the visitor’s consent once it is known on the page, then at every change	new in 2.0
`smootify:variant_changed`	a product’s variant changed after its first render (`element` is the product on the page)	new in 2.0

Events dispatched on the element instead of document: productLoaded, changeVariant, changePlan, smootify:product_reload, smootify:reload, imageChanged, quantityChanged, addon:state_change, sm:add_to_cart:connected, smootify:price_render, smootify.renderedMetafields, custom:toggle.

Filters

Filter	What it changes
`add_to_cart_lines`	The lines about to be added to the cart: the add to cart forms (the main line and its add-ons at once), boxes, direct add, buy again, `addToCart`, `addBoxToCart` and `/cart/add.js`. The message of an error a filter throws shows in the form and goes out with `smootify:errors`.
`checkout_url`	Where the visitor goes to check out: the checkout url (or the invoice of a draft order), from the cart’s checkout button, a buy now or `Smootify.checkout()`. Answer another url (parameters added, another checkout) or `false` to keep the visitor here (terms not accepted, a minimum order); the message of an error a filter throws shows in the cart. `smootify:initiate_checkout` goes out only when the visitor leaves.
`draft_order_data`	The draft order about to be created (Draft Orders, server plan): a quote, or a checkout or buy now with a custom price. An error a filter throws shows in the cart or the form.
`metafield_definitions`	The metafields the products and the cart ask Shopify for, for each kind of `[metafield]` element on the page (add the ones a script reads, remove the ones nobody shows). Synchronous: it cannot stop, and an error it throws is logged and the filter skipped.