cart/add.js Returns Wrong Quantity — data.quantity vs cart.item_count Explained
Your add-to-cart button calls /cart/add.js, the request succeeds, but the cart counter in your header shows the wrong number. This is one of the most common cart AJAX bugs in Shopify themes and the cause is always the same: using data.quantity from the cart/add.js response to update the cart counter. data.quantity is the quantity of the item just added — not the total number of items across the entire cart.
What cart/add.js actually returns
The /cart/add.js endpoint returns a line item object representing the product just added. Its quantity property is the quantity of that specific line item — not the cart total. If the cart already has 3 items and you add 1 more, data.quantity returns 1, not 4. Using data.quantity to update a counter that should show total cart items is always incorrect.
The correct way to get total cart quantity
After a successful cart/add.js call, make a second request to /cart.js to fetch the complete cart object. The response includes item_count (total number of items across all line items, accounting for quantities) and items (the complete line items array). Use cart.item_count to update your header counter: fetch('/cart.js').then(r => r.json()).then(cart => updateCounter(cart.item_count)).
Using Section Rendering API to avoid a second request
The most efficient pattern is Shopify's Section Rendering API. After cart/add.js succeeds, re-render the cart sections in a single request: fetch('/?sections=cart-drawer,cart-icon-bubble').then(r => r.json()).then(sections => { document.querySelector('.cart-icon-bubble').outerHTML = sections['cart-icon-bubble']; }). This updates the cart count and drawer content in one round trip without manually building HTML from JSON.
Handling add-to-cart errors
cart/add.js returns HTTP 422 when a product cannot be added — out of stock, quantity limit reached, or invalid variant. Always handle the error case: the response body contains a description property with the reason. Display this error to the user rather than silently failing. Implement a loading state on the button during the request and restore it whether the request succeeds or fails.
The fix: before and after
// CODE_COMPARISON
Frequently asked questions
- What is the difference between item_count and items.length in cart.js?
item_count is the sum of quantities across all line items. If you have 2 units of product A and 3 units of product B, item_count is 5. items.length is the number of unique line items (distinct product/variant combinations), which is 2. For a header cart counter showing total items, use item_count. For showing number of distinct products, use items.length.
- Why does cart/add.js return data.quantity as 1 even when I add 2 items?
data.quantity reflects exactly the quantity you passed in the request body. If you POST {quantity: 2}, data.quantity returns 2 — the quantity of the just-added line item. This is still not the cart total. Always fetch /cart.js separately for the accurate total count across all line items.
- Should I use cart/add.js, cart/update.js, or cart/change.js?
cart/add.js is for adding new line items to the cart. cart/update.js updates quantities using line number indexes — fragile if cart items change. cart/change.js updates a specific line item by its unique key from cart.js — this is the preferred method for quantity selectors in cart drawers because the key is stable.
// SCAN_YOUR_CODE
Does your theme have this bug?
Paste your code. Syphio automatically detects and fixes this error and hundreds of others — in seconds.
Check my JavaScript →