The Shopify AJAX Cart API allows developers to interact with the cart directly from the storefront using JavaScript.
It is one of the most important tools for building modern cart experiences.
What Is the Shopify AJAX Cart API?
Essentially it's a set of storefront endpoints that allow you to add, update, remove, and read cart data using JavaScript, without reloading the page.
It works entirely on the frontend and communicates with Shopify using simple HTTP requests such as:
- /cart/add.js
- /cart.js
- /cart/change.js
- /cart/update.js
The API is purely session-based, which means it uses the visitor’s browser session and does not require any authentication or access tokens.
This makes it ideal for theme and UI interactions.
However, the AJAX Cart API is not a replacement for the Admin API.
It cannot create orders, modify products, or access customers or store data.
It is also not meant for backend logic or automation. Its purpose is strictly limited to managing the cart experience on the storefront.
When to Use the AJAX Cart API (and When Not To)
Use the AJAX Cart API when you want to:
- Add products to the cart without page reloads instead of a traditional form submission
- Build slide carts, drawer carts, or mini carts
- Implement product upsells or cross-sells
- Update quantities dynamically from the UI
- Enables quick add functionality on collection and product listings
Do not use the AJAX Cart API when you need to:
- Access protected store data
- Modify products, orders, or customers
- Build server-side workflows
In those cases, the Admin API or Shopify Flow is the correct choice.
How the Shopify Cart Works (High-Level Mental Model)
Shopify’s cart is a cart object that exists per browser session. It is tied to browser cookies, not to a customer account, which means even logged-out visitors can have a cart.
A cart is automatically created the moment a product is added and Shopify manages it behind the scenes for each visitor.
This session-based behavior is what allows the AJAX Cart API to work without authentication and update the cart instantly on the storefront and simply lets you read and modify that cart using JavaScript.
Adding a Product to the Cart with the AJAX Cart API
The most common use case of the Shopify AJAX Cart API is adding products to the cart using JavaScript instead of a traditional form submission.
To do this, you send a POST request to /cart/add.js with the required data.
Required Data: Variant IDs, Quantity, Properties
Required fields:
- id → Variant ID (not product ID)
- quantity → Number of items
Optional fields:
- properties → Custom line item data (e.g. engraving text, gift notes)
If the variant ID is invalid or sold out, Shopify will return an error.
Using /cart/add.js (Code Example )
Here is a simple example of adding a product variant to the cart:
fetch('/cart/add.js', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
id: 1234567890,
quantity: 1
})
})
.then(response => response.json())
.then(data => {
console.log('Item added:', data);
})
.catch(error => {
console.error('Error:', error);
});
Reading Cart Data with /cart.js
This endpoint returns the complete cart data, including all line items, the total cart price, the item count, and any cart attributes.
It is commonly used to refresh cart drawers, and keep the UI in sync after cart updates, ensuring the storefront always reflects the latest cart state.
Updating Cart Items with the AJAX Cart API
To update quantities or remove items, Shopify provides endpoints like:
- /cart/change.js → Change a specific line item
- /cart/update.js → Update multiple items at once
Setting a quantity to 0 removes the item from the cart.
This is how plus/minus buttons and remove icons usually work in modern themes.
Handling Errors and Edge Cases
When working with the AJAX Cart API, you should always handle errors such as:
- Sold-out variants
- Invalid or missing variant IDs
- Quantity limits
- Network failures
Shopify returns structured error messages in JSON format as part of the AJAX response.
These errors should be properly handled and reflected in the UI instead of being ignored.
During development, the full error response can be inspected directly in the browser’s Network tab.
Real World Example Overview:
Implementing an In-Cart Upsell in the Dawn Theme Using Existing Theme Components
In this example, we add an in-cart upsell to the Dawn theme by reusing existing components that already use the AJAX Cart API, rather than building custom cart logic from scratch.
(This was actually an interview challenge for Shopify Developers at an agency I know)
The goal is simple:
- when a product is added to the cart, we suggest another product as an upsell.
- If the customer adds the upsell product, it disappears from the cart drawer.
- If they remove it later, the upsell appears again
Since Dawn already provides a structured AJAX cart system, we simply trigger the same logic used by standard add-to-cart buttons.
This keeps cart behavior consistent and ensures the cart UI updates automatically without additional custom code.
If you want to see this upsell flow implemented step by step using the Dawn theme, watch the full video walkthrough linked below
And if you want to learn how to become a paid Shopify Developer, keep an eye on our Bootcamp. (It's really good)