Shopify AJAX Cart Drawer — Quantity Updates Without Reload

The Shopify Cart AJAX API endpoint — /cart/change.js — is a POST endpoint available on every Shopify storefront with AJAX cart enabled. It accepts a JSON body with two fields: id (the variant ID) or line (the 1-based line index), and quantity (the absolute new quantity, not a delta). Setting quantity to 0 removes the item. The response is the full cart object — { token, note, attributes, total_price, total_weight, item_count, items: [{ key, id, quantity, line_price, ... }] }. Unlike the GraphQL Storefront API, this endpoint requires no authentication token and is available on unauthenticated storefronts. The response includes every cart field, so one API call after a quantity change gives you line prices, item count, and totals — no need for a second request. The /cart/update.js endpoint (alternative) accepts an updates object with multiple line changes at once, but it overwrites the entire cart state rather than mutating a single line.

Line item keys vs line indexes. Every cart item has two identifiers: the line (1-based positional index, changes when items are added or removed) and the key (a colon-separated string like 4123456789:abc123 that uniquely identifies a variant + any line-item properties). Step 2 uses the 1-based index (forloop.index in Liquid stored in data-line) because it’s the simplest approach and matches the API’s line parameter directly. Step 5 upgrades to the item key (data-key="{{ item.key }}" stored as the debounce map key) because the index can drift — if a previous item is removed while a debounced update is pending, the index for the remaining items shifts by one, and the API call targets the wrong item. The key is immutable and survives cart mutations. In production, always use the key.

The optimistic update pattern works in three phases: 1) Store state — capture the current quantity, price, and button state before any DOM changes. 2) Render new state — update the DOM immediately (quantity text changes, button disables, price stays stale). 3) Reconcile on response — on success: apply the server-confirmed price and release button lock. On failure: restore all three stored values. The price is deliberately not optimistically updated because the line price depends on the cart’s total recalculation (line price = item price × new quantity, with any quantity-break discounts applied). Guessing the price and being wrong is worse than showing a slightly stale price for 200ms. The quantity is safe to optimistically update because it’s just an integer change — the user knows what they clicked. The button disable prevents double-clicks in the 200ms window.

Debouncing replaces the naive “one click = one API call” pattern. Each click resets a 300ms timer. If the user clicks “+” five times rapidly, the quantity text updates optimistically on every click (immediate visual feedback), but only one API call fires — 300ms after the last click, with the final quantity. The Map stores one timer per line item key, so clicking on item A doesn’t cancel item B’s pending request. The commit() method captures the quantity at debounce start (oldQty) and re-reads the DOM at debounce end (currentQty) — this is important because the user might click “+” twice, then “−” once, all within 300ms. The final quantity sent to the API is what’s currently displayed, not what was displayed when the first click happened. Without debouncing, five rapid clicks produce five API calls in parallel — the server processes them in arbitrary order, and the last response to arrive (not the last click) determines the visible state. This is the source of the “my cart quantity is wrong after fast clicking” bug.

Error recovery happens at two levels. The .catch() on the fetch promise handles network-level failures (offline, DNS failure, CDN outage) and HTTP error responses (Shopify returning a 422 for an invalid quantity, 5xx for server errors). The catch restores the pre-click quantity and price — the DOM returns to the last known valid state. The showError() method creates an ephemeral toast element: a fixed-position banner at the top of the viewport that auto-removes after 3 seconds. The toast checks for an existing #cart-toast element before creating one — no duplicate toasts, no element leak. On the error path, the minus button re-enables and the stale quantity is shown. The user can immediately retry. This pattern — instant retryability without a page reload — is the core value proposition over default Shopify cart behavior, which requires navigating to /cart after every error.

Create the cart drawer section. If your theme already has a cart drawer, skip to step 2 and integrate the quantity button markup into the existing loop. If you’re building from scratch, create sections/cart-drawer.liquid with the basic drawer structure:

<div class="cart-drawer" id="cart-drawer">n  <div class="cart-drawer__overlay"></div>n  <div class="cart-drawer__panel">n    <h2>Your Cart</h2>n    {% for item in cart.items %}n      <div class="cart-drawer__item" data-line="{{ forloop.index }}" data-key="{{ item.key }}">n        <img src="{{ item.image | image_url: width: 120 }}" alt="{{ item.title | escape }}">n        <div class="cart-drawer__details">n          <span class="cart-drawer__title">{{ item.title }}</span>n          <div class="cart-drawer__qty">n            <button class="qty-btn qty-btn--minus" type="button" aria-label="Decrease quantity"&minus;</button>n            <span class="qty-value">{{ item.quantity }}</span>n            <button class="qty-btn qty-btn--plus" type="button" aria-label="Increase quantity"+</button>n          </div>n        </div>n        <span class="cart-drawer__price">{{ item.line_price | money }}</span>n      </div>n    {% endfor %}n  </div>n</div>

The data-key="{{ item.key }}" attribute is critical for the production version — it uniquely identifies variant-specific line items and survives cart mutations where indexes shift.

Wire the JavaScript module. Copy the Step 5 code into assets/cart-drawer.js. In layout/theme.liquid, add the script tag near </body>:

{{ 'cart-drawer.js' | asset_url | script_tag }}

The module initializes itself on DOMContentLoaded — no inline script tags, no manual new CartDrawer() call. It checks for the existence of .cart-drawer at construction and silently exits if the element isn’t on the page, so it’s safe to include on every page. The event listener is delegated on the .cart-drawer element itself, so dynamically added cart items (after adding a product via AJAX) are automatically handled — no MutationObserver needed.

Style the quantity buttons. Add these CSS rules to your theme’s stylesheet. The quantity controls should look like buttons, not form inputs — they’re interactive targets on a touch device, so minimum 36px tap area:

.cart-drawer__qty {n    display: inline-flex;n    align-items: center;n    gap: 8px;n    border: 1px solid #ddd;n    border-radius: 4px;n    padding: 0;n}nn.qty-btn {n    width: 36px;n    height: 36px;n    display: flex;n    align-items: center;n    justify-content: center;n    background: none;n    border: none;n    font-size: 1.25rem;n    cursor: pointer;n    color: #333;n    transition: opacity 0.2s;n}nn.qty-btn:hover  { background: #f5f5f5; }n.qty-btn:disabled { opacity: 0.3; cursor: not-allowed; }nn.qty-value {n    min-width: 24px;n    text-align: center;n    font-weight: 600;n}nn.cart-drawer__item--removing {n    opacity: 0;n    transform: translateX(20px);n    transition: opacity 0.3s, transform 0.3s;n}

The qty-btn:disabled rule gives low-opacity visual feedback during API calls — the button is greyed out but still in place, so the layout doesn’t shift. The cart-drawer__item--removing class triggers a fade-and-slide-out animation before the element is removed from the DOM. The 36px width/height exceeds the WCAG minimum touch target of 24px and matches Google’s recommended 48dp target (36px is close enough for most designs).

Add keyboard support. The quantity buttons should respond to Enter and Space keys. Add this handler inside the onClick method or as a separate onKeyDown listener. Since the buttons are <button> elements (not <div>), they already respond to Space and Enter natively — no extra code needed for basic keyboard activation. To add arrow-key navigation between quantity groups, add this to the CartDrawer class:

this.drawer.addEventListener('keydown', e => {n    if (!e.target.classList.contains('qty-btn')) return;n    const items = [...this.drawer.querySelectorAll('.qty-btn')];n    const idx   = items.indexOf(e.target);n    if (e.key === 'ArrowDown' && idx + 2 < items.length)n items[idx + 2].focus();n if (e.key === 'ArrowUp' && idx - 2 >= 0)n        items[idx - 2].focus();n});

The +2 offset skips to the same button (plus or minus) on the next item — because buttons alternate minus/plus per row.

Add animation on quantity change. A brief scale pop on the quantity number confirms the click was registered — especially important for touchscreens where there’s no hover state. Add this CSS:

.qty-value--changed {n    animation: qtyPop 0.2s ease-out;n}nn@keyframes qtyPop {n    0%   { transform: scale(1); }n    50%  { transform: scale(1.3); }n    100% { transform: scale(1); }n}

Then add/remove the class in the click handler: qtyEl.classList.add('qty-value--changed'); setTimeout(() => qtyEl.classList.remove('qty-value--changed'), 200); The class triggers a 200ms scale animation — the same duration as the CSS, so the class can be removed after one animation cycle.

Sync the cart count badge in the header. The syncCount() method in Step 5 already handles this for simple setups — it looks for a .cart-count-badge element and updates its text. If your header has multiple badge instances (mobile + desktop), update the method:

syncCount(count) {n    document.querySelectorAll('.cart-count-badge').forEach(badge => {n        if (count !== undefined) badge.textContent = count;n    });n}

If your cart count is rendered as a Liquid variable in the header (not updated via JavaScript), you’ll need to handle the badge via AJAX. Alternative: after every successful cart mutation, fetch /cart.js (GET) to get the full cart state including item_count, then update every badge on the page. This adds one extra network request per mutation but guarantees consistency. For performance, cache the badge elements in the constructor (this.badges = document.querySelectorAll('.cart-count-badge')) so syncCount() doesn’t re-query the DOM.