Developer API & events

Luv Cart works on most themes with no code. When you want your own buttons, apps or analytics to work with the drawer, everything on this page is public and safe to build on.

Open the drawer from anything

Add data-luvcart-open to any element and a click on it opens the drawer:

<button type="button" data-luvcart-open>View cart</button>

While the drawer is open, the page's <html> element carries data-luvcart-open="true", so other scripts, such as a popup or a chat bubble, can wait, and your CSS can react:

html[data-luvcart-open="true"] .chat-bubble { display: none; }

window.LuvCart

Available once the drawer has loaded (listen for luvcart:ready):

• open(), close(), toggle() and isOpen()
• refresh(): reload the cart and redraw, after your own code changes it
• getCart(): the cart as the drawer last loaded it
• addItem(variantId, quantity, properties): add a variant to the cart; returns a promise
• formatMoney(cents): an amount in your store's money format
• on(name, fn) and off(name, fn): subscribe to the events below by name, without the luvcart: prefix (for example LuvCart.on("added", fn)), and unsubscribe
• version and build: which drawer version is running

function whenLuvCart(fn) {
  if (window.LuvCart) fn();
  else document.addEventListener("luvcart:ready", fn, { once: true });
}
whenLuvCart(async function () {
  await LuvCart.addItem(44012345678, 1, { _source: "quiz" });
  LuvCart.open();
});

Events

Luv Cart dispatches these on document. Each event's detail includes the cart as detail.cart, plus what the event is about.

• luvcart:ready: the drawer has loaded
• luvcart:open and luvcart:close
• luvcart:updated: the cart changed
• luvcart:added and luvcart:removed: a line was added or removed
• luvcart:upsell-added: a shopper added an upsell
• luvcart:gift-added and luvcart:gift-removed
• luvcart:reward-unlocked: the cart reached a reward step
• luvcart:checkout: the shopper pressed checkout

document.addEventListener("luvcart:added", function (e) {
  console.log("Items in cart:", e.detail.cart.item_count);
});

Luv Cart listens, too. Dispatch luvcart:refresh on document after your code changes the cart and the drawer redraws. It also answers the common theme events cart:refresh, cart:updated and cart-drawer:open.

Hooks

Define window.LuvCartHooks to adjust what the drawer does:

window.LuvCartHooks = {
  // Return false to skip an add (items: the lines about to be added)
  beforeAdd: function (items) { return true; },
  // Return false to stop checkout, for example until terms are accepted
  beforeCheckout: function (cart) {
    var box = document.querySelector("#terms");
    return !box || box.checked;
  },
  // Reorder, trim or extend the upsell list, then return it
  upsells: function (list) { return list.slice(0, 2); }
};

Settings for unusual themes

Under Behavior in the app you can list CSS selectors for your theme's own cart drawer to hide, for extra buttons that should open Luv Cart, and for add-to-cart buttons Luv Cart should handle. Most themes need none of these.

Luv Cart's marks on lines and orders

These properties start with an underscore, so shoppers don't see them in the drawer or at checkout. You'll find them on the order in your Shopify admin.

• _luvcart_gift (line property): the line is a Luv Cart gift
• _luvcart and _luvcart_src (line properties): the line was added from an upsell, and where the suggestion came from
• _luvcart (cart attribute): the order went through the drawer

Don't add these yourself: a gift line is only free when Luv Cart added it for a gift the cart earned.

Questions? hi@customerluv.app — a founder answers every message.