Is your Shopify theme agent-ready? Start with the cart

Here is a bug that did not exist three weeks ago. A shopper opens your store, asks their browser's AI assistant to add the large size to the cart, and it works. The cart genuinely has the item. Then they click your cart drawer and it is empty. Not stale, not slow. Empty, because your drawer has never once asked the cart what is in it. It only knows what it put there.

On 5 August 2026 Shopify turned on WebMCP for every Liquid storefront, which lets an AI agent in the browser call a tool named update_cart. Those cart tools go through standard storefront actions, the same functions apps use. If your theme writes to the cart with its own fetch and updates its own UI in the response handler, you now have two systems editing one cart and only one of them is listening.

The pattern that is about to age badly

Open almost any custom theme built in the last five years and you will find something close to this. It is not incompetent code. It was the normal way to build an AJAX cart, and it works perfectly right up until something other than your own button changes the cart.

1// Adds to cart, then hand-updates the drawer from the response.2async function addToCart(variantId, quantity) {3  const res = await fetch("/cart/add.js", {4    method: "POST",5    headers: { "Content-Type": "application/json" },6    body: JSON.stringify({ id: variantId, quantity }),7  });8  const line = await res.json();9 10  // The drawer's only source of truth is this response.11  renderDrawerLine(line);12  incrementBadge(quantity);13  openDrawer();14}

Three separate assumptions are baked in here, and an agent breaks all of them at once. The drawer assumes it caused every change. The badge assumes it can track the count by arithmetic rather than by reading it. And the open-drawer call assumes a change always came from a human clicking a button, which is why agent-driven adds can pop your drawer open at a moment the shopper did not ask for.

The five-minute audit

You do not need an agent to test this. Every check below runs in your browser console on your own storefront, because you are simulating exactly what the agent does: changing the cart through the standard action rather than through your UI.

1// 1. Does the theme expose the standard actions at all?2console.log(typeof Shopify?.actions?.updateCart);   // expect "function"3 4// 2. Change the cart the way an agent would: not via your button.5await Shopify.actions.updateCart({6  lines: [{ merchandiseId: "gid://shopify/ProductVariant/YOUR_ID", quantity: 1 }],7});8 9// 3. Now look at the page WITHOUT reloading.10//    Did the cart count update? Did the drawer contents update?11//    If either says zero, your UI is not listening.12 13// 4. Does anything at all hear the event?14addEventListener("shopify:cart:lines-update", (e) =>15  console.log("theme heard it:", e.detail),16);

Step three is the whole test. If the badge still reads zero while /cart.js reports an item, your theme and the cart disagree, and every agent interaction from here will surface that disagreement to a shopper.

The fix, in two moves

1. Write through the standard action

Shopify.actions.updateCart does the write and emits the event that everything else on the page is listening for, including apps. A raw fetch to /cart/add.js changes the cart silently as far as the rest of the page is concerned.

1async function addToCart(variantId, quantity) {2  // One call. It writes AND announces.3  await Shopify.actions.updateCart({4    lines: [{ merchandiseId: variantId, quantity }],5  });6  // Note what is NOT here: no rendering. That happens below.7}

2. Render from the event, never from the response

This is the move that makes the theme agent-ready, and it is a genuine inversion of how most cart code is written. Your UI stops being something you update after an action and becomes something that reflects cart state whenever cart state changes, no matter who changed it.

1// One listener. Every writer on the page flows through it:2// your buttons, installed apps, and now AI agents.3addEventListener("shopify:cart:lines-update", (event) => {4  renderDrawer(event.detail);5  renderBadge(event.detail);6});7 8// Opening the drawer stays tied to intent, not to cart changes.9// An agent adding an item should not throw UI at the shopper.10addToCartButton.addEventListener("click", () => Shopify.actions.openCart());

Separating the open from the update is the subtle one. Under the old pattern they were the same event, because the only way the cart changed was somebody clicking. Now they are different questions: what does the cart contain is answered by the event, and should the drawer be visible is answered by what the shopper did.

Cart attributes changed too

One day after WebMCP shipped, Shopify extended the standard action set so cart attributes update through it as well, with a matching shopify:cart:attributes-update event. If your theme writes gift messages, delivery notes, or engraving text, the same rule applies: write through the action, re-render from the event.

Why this was always the right answer

Nothing in the fix above is new advice. Shopify has recommended the standard cart mechanisms for years, and the reasons given were mostly about app compatibility: route your writes properly so a subscription app or an upsell app does not fight your theme. It was easy to treat that as a nice-to-have, because most stores could get away with ignoring it.

What changed on 5 August is not the recommendation. It is the cost of ignoring it. A convention you could quietly skip has become a thing that produces a visible, shopper-facing bug, on a surface Shopify enabled without asking. That is a fairly common shape for platform work, and it is the argument for following the documented mechanism even when a shortcut demonstrably works: the shortcut is only correct until the platform adds a second actor.