Liquid Ajax Cart

Liquid Ajax Cart automatically reloads the HTML content of containers marked with the data-ajax-cart-section attribute whenever the Shopify cart changes.

It leverages Shopify's Bundled section rendering to request re-rendered HTML for specific theme sections alongside Cart API responses. Because of this mechanism, the data-ajax-cart-section attribute must be applied within Shopify sections.

A Request state is a JavaScript object created for every Shopify Cart API Ajax request. It serves as a central container where Liquid Ajax Cart stores information about the request, its payload, the initiator, and the resulting response or error. You can access this object within liquid-ajax-cart:request-start and liquid-ajax-cart:request-end event handlers to inspect or modify request behavior.

{
  "endpoint": "/cart/add.js",
  "requestBody": {"items": [{"id": 40934235668668, "quantity": 1}], "sections": "my-cart"},
  "requestType": "add",
  "info": {
    "initiator": Element {},
    "cancel": false
  },
  "responseData": {
    "ok": true,
    "status": 200,
    "body": {…}
  },
  "extraResponseData": {
    "ok": true,
    "status": 200,
    "body": {…}
  }
}

Liquid Ajax Cart automatically manages the .js-ajax-cart-empty CSS class on the <body> tag to help you style your store differently when the cart is empty.

When the cart is empty, the class .js-ajax-cart-empty is added to the <body>. When items are added to the cart, this class is removed.

Note: The documentation title refers to .js-ajax-cart-empty, but the text describes the logic for adding/removing a class based on cart state. Use this class in your CSS to hide/show elements (like

Depending on the outcome of the Shopify Cart API request, you should check different properties in the Request state:

• Successful Requests: Check responseData. If responseData.ok is true, the request was successful (status 200–299).
• Failed Requests (No Response): If the request failed before a response was received (e.g., due to network issues), responseData will be null. In this case, look for the fetchError property to diagnose the issue.
• Additional Data: If Liquid Ajax Cart had to perform an extra POST /cart/update.js request (to fetch missing cart state or extra sections), the result is stored in extraResponseData.

The library automatically appends the CSS class js-ajax-cart-not-empty to the <html> tag whenever the user's cart contains items. You can use this class in your CSS to conditionally show or hide elements (like a cart quantity badge) only when the cart is not empty.

To implement this, use a CSS selector starting with html.js-ajax-cart-not-empty to target child elements.

/* Example: Show the quantity badge only when the cart is not empty */
html.js-ajax-cart-not-empty .header__cart-quantity {
  display: inline-block;
}

A mutation is a custom JavaScript function that allows you to automatically add or remove items from the Shopify cart based on specific logic (e.g., promotions or cart corrections).

How it works:

1. You define a function that inspects the current cart state.
2. You register this function using the mutations configuration parameter.
3. Liquid Ajax Cart executes your function when the page loads and every time the cart changes.
4. If your function returns an object containing a requests array, Liquid Ajax Cart performs the specified Shopify Cart API Ajax requests.

This is useful for scenarios like:

• Adding a free gift when a price threshold is met.
• Removing a specific product if another product is missing.
• Enforcing cart limits.

All Shopify Cart API requests in liquid-ajax-cart are managed via a queuing system to prevent race conditions. Requests are grouped into sequential queues. The system processes all requests in the first queue in order; once the first queue is empty, it is removed, the second queue becomes the first, and the process repeats.

This mechanism ensures that multiple asynchronous cart operations (like adding items or changing quantities) are executed in a predictable, serial order.

When making requests in v2, note the following parameter name changes and behaviors:

• Callbacks: firstComplete and lastComplete are now firstCallback and lastCallback.
• Queue Priority: The newQueue parameter is replaced by important.
  • When important is true, the request is added to the beginning of the request queue.
  • The default value for important is false.

The State is a JavaScript object that holds all information related to the user's cart. It is automatically updated by Liquid Ajax Cart after every successful Shopify Cart API request.

Important: To ensure the State remains synchronized, always use the functions provided in the Cart Ajax API requests reference instead of making direct Shopify Cart API calls. Using the library's built-in methods ensures the internal state is updated correctly.

Liquid Ajax Cart does not execute Shopify Cart API Ajax requests immediately. Instead, it manages them through a Queue of requests.

When a request is initiated (e.g., via an "Add to cart" button click or a direct method call) and the queue is currently empty, the following sequence occurs:

1. The request is added to the Queue.
2. The liquid-ajax-cart:queue-start event is dispatched on the document.
3. The library begins performing the request(s).