Cart API reference

Use the POST /{locale}/cart/add.js endpoint to add one or multiple variants to the cart.

In the following example, quantity is the amount of the variant that you want to add and id is the variant ID of that variant. You can add multiple variants to the cart by appending more objects in the items array.

Below is a simplified POST request using the fetch API. The formData object is built in JavaScript, so the Content-Type should be set to application/json in the headers object. The response is the JSON of the line items associated with the added variants. If an item is already in the cart, then quantity is equal to the new quantity for that item.

Alternatively, you can use the FormData constructor and target the desired add-to-cart form:

The response for a successful POST request is a JSON object of the line items associated with the added items.

If an added item was already in the cart, then the quantity is equal to the new quantity for that cart line item. However, if the same items have differing prices, properties, or selling plans, then they'll be split into their own line items.

If the specified quantity for an item exceeds the available stock (e.g., attempting to add 20 items when only 10 are available), the cart will instead add the maximum available quantity. The error returned in JSON format is as follows:

If the product is entirely sold out, then the following error is returned:

If the product is not sold out, but all of its stock is in the cart, then the following error is returned:

You can add a variant to the cart with line item properties using the properties property. Its value must be an object of key-value pairs.

You can add a variant with a selling plan to the cart using the selling_plan parameter. Its value must be the selling plan ID.

Use the GET /{locale}/cart.js endpoint to get the cart as JSON.

All monetary properties are returned in the customer's presentment currency. To check the customer's presentment currency, you can use the currency field in the response. To learn more about selling in multiple currencies, refer to Migrate your app to support multi-currency.

Use the POST /{locale}/cart/update.js endpoint to update the cart's line item quantities, note, or attributes. You can submit a serialized cart form, or submit separate updates to a cart's line items, note, or attributes.

To update line item quantities, you can make a POST request with an updates object. The updates object must contain key-value pairs where the value is the desired quantity, and the key is one of the following:

• The line item's variant_id
• The line item's key

A cart can have multiple line items that share the same variant_id. For example, when variants have different line item properties, or automatic discounts create variants at different prices. Because of this, it's recommended to use the line item key to ensure that you're only changing the intended line item.

The line item key is not persistent for the lifetime of a line item, it changes as characteristics of the line item change. This includes, but is not limited to, properties and discount applications.

The following POST request yields the same result:

The /{locale}/cart/update.js endpoint adds new line items to the cart if the variant_id provided doesn't match any line item already in the cart. However, if the variant_id matches multiple line items, then the first matching line item is updated.

You can remove items from the cart by setting the quantity to 0:

You can also submit an array of numbers to /{locale}/cart/update.js, provided the size of the array matches the number of line items in the cart. Each number in the array sets the quantity for the corresponding line item in the cart. For example, if you have 3 line items in the cart with quantities 1, 2, and 3, and you want to change those quantities to 3, 2, and 1, then you can use the following:

To update the cart note, you can make a POST request with a note character string:

To update cart attributes, you can make a POST request with an attributes object. The attributes object must contain key-value pairs where the key is the name of the attribute you want to update, and the value is the attribute value:

The following POST request yields the same result:

The JSON of the cart.

If a variant ID is provided that either doesn't exist or isn't available in the online store channel, then the endpoint returns the following error:

Use the /{locale}/cart/change.js endpoint to change the quantity, properties, and selling_plan properties of a cart line item. Only items already in your cart can be changed, and you can change only one line item at a time.

The POST data requires either an id or line property to identify the line item to be changed.

The value of the id property can be one of the following:

• The line item's variant_id
• The line item's key

A cart can have multiple line items that share the same variant_id. For example, when variants have different line item properties, or automatic discounts create variants at different prices. Because of this, it's recommended to use the line item key to ensure that you're only changing the intended line item.

A cart can have multiple line items that share the same variant_id. For example, when variants have different line item properties, or automatic discounts create variants at different prices. To account for this, you can use the line property when updating the cart.

The value of line is the 1-based index position of the item in the cart.

The value of thequantity property represents the new quantity you want for the line item. It must be an integer.

You can remove a line item by setting the quantity to 0:

The properties property sets the line item properties. Its value must be an object of key-value pairs.

Whenever a POST request includes properties, it overwrites the entire properties object. Any key-value pairs that were already in the properties object are erased.

It's not possible to set a line item's properties property to an empty object once a value is set. If you need to remove all line item properties, then you need to remove the entire line item.

The selling_plan property sets the line item selling plan. Its value must be one of the following:

• The selling plan ID: To set a specific selling plan for the line item.
• null or an empty string: To remove any selling plan from the line item.

The JSON of the cart.

If the item that you're attempting to change isn't already in the cart, then /{locale}/cart/change.js doesn't add it. Instead, it returns a 400 error:

Use the POST /{locale}/cart/clear.js endpoint to set all quantities of all line items in the cart to zero.

The JSON of an empty cart. This does not remove cart attributes or the cart note.

Use the POST /{locale}/cart/prepare_shipping_rates.json and GET /{locale}/cart/async_shipping_rates.json endpoints to generate shipping rates:

• The POST /{locale}/cart/prepare_shipping_rates.json endpoint initiates the process of calculating shipping rates for the cart given a destination.
• The GET /{locale}/cart/async_shipping_rates.json endpoint returns the shipping rates results if the calculations have finished.

null

Use the GET /{locale}/cart/shipping_rates.json to get estimated shipping rates.

Private line item properties and private cart attributes are used when you need to attach information to either cart line items or the entire cart, and you don't want the properties and attributes to be visible to the online store's visitors.

Both private properties and private cart attributes are visually hidden at checkout, but are visible on the Order details page in the Shopify admin.

To make a line item property private, prepend an underscore (_) to the key. For example, to add a variant to cart with a private _foo property using the /{locale}/cart/add.js endpoint:

The properties property can have a mix of private and public line item properties:

Private line item properties are available in the Liquid line_item.properties object and Ajax API. To hide private properties on the storefront, you must modify the theme's codebase.

In the following example, all properties items that begin with _ in Liquid are filtered out:

To make a cart attribute private, append a double underscore (__) to an attribute name.

Private cart attributes are not available in the Liquid cart.attributes object or the Ajax API. This means there is no code modification required to hide them in theme files. Private cart attributes also do not affect the page rendering, which allows for more effective page caching.

Bundled section rendering allows you to request the HTML markup for up to five sections you might want to update based on an initial call to the Cart API, within that same call.

Bundled section rendering is available for the following Cart API endpoints:

• /{locale}/cart/add
• /{locale}/cart/change
• /{locale}/cart/clear
• /{locale}/cart/update

To request sections, you can include a sections parameter in your API call data:

By default, sections are rendered in the context of the current page, based on the HTTP Referer header. However, you can specify any other page using the sections_url parameter. The sections_url must begin with a / and can include query parameters like q and page.

The HTML for the requested sections is included under the sections key of the returned JSON. Each section can be identified by the same ID that was passed in the request.

Sections are rendered after the data modifications from the request are completed. Because of this, rendering errors don't affect the response status of the API call. Sections that fail to render are returned as null, so you should account for this possibility.

Passing invalid values for the sections or sections_url parameters, such as a sections_url that doesn't begin with /, causes the entire request to return an HTTP 400 Bad Request status. However, this doesn’t mean that the rest of the request didn’t succeed.