Shopify AJAX API

Apps written for Shopify themes call the theme’s AJAX endpoints, such as /cart.js or /cart/add.js. An Astro site has no Shopify theme, so Smootify answers these calls on the page itself, from Shopify’s Storefront API, with the same response shape a theme gets. The cart they change is the page’s cart. This page lists what is answered and how to make an app’s code work with it.

How it works

• What is intercepted. fetch and XMLHttpRequest calls to the site’s own address, and to the store’s .myshopify.com address, whose path is one of the endpoints below. Every other request goes out unchanged.
• Same cart as the page. A change through /cart/add.js, /cart/update.js (or their .json forms), /cart/change.js or /cart/clear.js goes through Smootify’s cart: the page’s cart updates as if the visitor had used it, and smootify:cart_updated goes out (with smootify:added_to_cart for an addition).
• Filters apply. Lines added with /cart/add.js go through the add_to_cart_lines filters, with no element in the context.
• The request address. As on Shopify, each answer carries the address of the request: response.url for fetch (its clones too), responseURL for XMLHttpRequest. Some app snippets tell an addition from a read by it.
• window.Shopify. Smootify also sets Shopify.shop, Shopify.locale, Shopify.country, Shopify.routes.root and Shopify.theme ("Smootify"), which theme scripts read.
• Shopify.actions.updateCart. The cart action of Shopify’s storefront web components, such as the Shopify Inbox chat. Smootify defines window.Shopify.actions.updateCart(payload) unless the page already has one: lines in the Storefront API shape (merchandiseId adds a line, the id of a /cart.json item key sets its quantity, 0 removes it), discountCodes replaces the codes, note sets the note. It answers { cart, userErrors }, with the cart in the Storefront API shape and line ids it accepts back. Smootify also writes Shopify’s cart cookie, which these components read.

The endpoints

The same list is in the Reference: AJAX API.

products.json and collections/{handle}/products.json answer only their first page, because the Storefront API pages through results in another way.

Start the app’s code after Smootify

Smootify loads as an asynchronous module. A plain script at the end of the page runs before it: its /cart.js calls reach your site’s server, which answers 404, and a snippet that wraps window.fetch there never sees /cart/add.js. Two ways to wait:

• Change the snippet’s type to smootify-load. Smootify runs it right after smootify:loaded. Add data-type="module" if it was a module; its other attributes are kept. In an .astro file, add is:inline to the tag so that Astro leaves it as it is.
• Start it from a smootify:loaded listener registered in an is:inline script in the head of your layout, before Smootify finishes loading. The event fires once per page: code added later, by a tag manager for example, does not see it.

<script is:inline type="smootify-load">
  fetch("/cart/add.js", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ items: [{ id: 44012345678901, quantity: 1 }] }),
  }).then((response) => response.json());
</script>

For adding an app’s snippet to a page, see Shopify apps.

App proxy paths

Some Shopify apps call their own server through the store, on paths such as /apps/…, /a/…, /community/… or /tools/…. These app proxies need Shopify’s Online Store. Smootify does not answer them: the calls reach the network as they are, and your site answers 404. On the dev server and on a *.workers.dev address, the debugger names the calls.

Two exceptions keep working: Shopify Inbox’s /apps/ba-rev gets an empty answer, and the consent request to /api/unstable/graphql.json goes to the store.

An app that needs its proxy does not work on an Astro site.

Turn it off

When another script on the page answers these endpoints, turn Smootify’s emulation off in the options:

smootify({ siteId, userOptions: { ajaxApi: false } });

Put it in astro.config.mjs, in the options of the Smootify integration.

Where people get stuck