Cart API reference

The following Ajax calls can be used to interact with a cart during a customer's session. This API can be used to update cart line items, add cart attributes and notes, and see shipping rate estimates.

The coding examples provided below don't always use a callback for the sake of simplicity.

POST /cart/add.js

Use this to add one or multiple variants to the cart.

POST data

items: [
  {
    quantity: 2,
    id: 794864229
  }
]

Where quantity is how many you want to add of a particular variant, 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.

You can also send a serialized Add to Cart form:

jQuery.post('/cart/add.js', $('form[action="/cart/add"]').serialize());

You can add to the cart with line item properties, not just a quantity and ID:

jQuery.post('/cart/add.js', {
  items: [
    {
      quantity: 1,
      id: 794864229,
      properties: {
        'First name': 'Caroline'
      }
    }
  ]
});

Response

The JSON of the line items associated with the added variants.

Example:

{
  "items": [
    {
      "id": 794864229,
      "title": "Red Rain Coat - Small",
      "key": "794864229:03af7a8cb59a4c3c45595c76fa8cb53c",
      "price": 12900,
      "line_price": 12900,
      "quantity": 1,
      "sku": null,
      "grams": 0,
      "vendor": "Shopify",
      "properties": {},
      "variant_id": 794864229,
      "gift_card": false,
      "url": "/products/red-rain-coat?variant=794864229",
      "featured_image": {
        "url": "http://cdn.shopify.com/s/files/1/0040/7092/products/red-rain-coat.jpeg?v=1402604893",
        "aspect_ratio": 1.0,
        "alt": "Red rain coat with a hood"
      },
      "image": "http://cdn.shopify.com/s/files/1/0040/7092/products/red-rain-coat.jpeg?v=1402604893",
      "handle": "red-rain-coat",
      "requires_shipping": true,
      "product_title": "Red Rain Coat",
      "product_description": "A bright red rain coat for rainy days!",
      "product_type": "Coat",
      "variant_title": "Red",
      "variant_options": ["Red"],
      "options_with_values": [
        {
          "name": "Color",
          "value": "Red"
        }
      ]
    }
  ]
}

If an item was already in the cart, the quantity will be equal to the new quantity for that item.

Error responses

If the exact quantity specified for one of the items can't be added to the cart (for example if you are trying to add 9 items, 2 are already in the cart, and 10 are in stock), then no items are added the cart. The error returned is:

{
  "status": 422,
  "message": "Cart Error",
  "description": "You can't add more Messenger Bag to the cart."
}

Note that the error too is formatted as JSON.

The error code is:

422 (Unprocessable Entity)

If the product is entirely sold out, the error returned will say this:

The product '#{item.name}' is already sold out.

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

All #{item.inventory_quantity} #{item.name} are in your cart.

GET /cart.js

Use this 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, see Migrating to support multiple currencies.

Response

The JSON of the cart.

Example:

{
  "token": "1d19a32178501c44ef2223d73c54d16d",
  "note": "Hello!",
  "attributes": {
    "Gift wrap": "Yes"
  },
  "total_price": 9100,
  "total_weight": 0,
  "item_count": 3,
  "items": [
    {
      "id": 794864229,
      "properties": {},
      "quantity": 1,
      "variant_id": 794864229,
      "key": "794864229:03af7a8cb59a4c3c45595c76fa8cb53c",
      "title": "Red Rain Coat - Small",
      "price": 12900,
      "line_price": 12900,
      "final_price": 12900,
      "final_line_price": 12900,
      "sku": null,
      "grams": 0,
      "vendor": "Shopify",
      "taxable": true,
      "product_id": 388319916,
      "product_has_only_default_variant": false,
      "gift_card": false,
      "url": "/products/red-rain-coat?variant=794864229",
      "featured_image": {
        "url": "http://cdn.shopify.com/s/files/1/0040/7092/products/red-rain-coat.jpeg?v=1402604893",
        "aspect_ratio": 1.0,
        "alt": "Red rain coat with a hood"
      },
      "image": "http://cdn.shopify.com/s/files/1/0040/7092/products/red-rain-coat.jpeg?v=1402604893",
      "handle": "red-rain-coat",
      "requires_shipping": true,
      "product_title": "Red Rain Coat",
      "product_description": "A bright red rain coat for rainy days!",
      "product_type": "Coat",
      "variant_title": "Red",
      "variant_options": ["Red"],
      "options_with_values": [
        {
          "name": "Color",
          "value": "Red"
        }
      ]
    },
    {
      "id": 794864101,
      "properties": {},
      "quantity": 2,
      "variant_id": 794864101,
      "key": "794864101:816a55d9a53cd82281f8fdcfe967db14",
      "title": "Gray Fedora",
      "price": 2650,
      "line_price": 0,
      "final_price": 2650,
      "final_line_price": 5300,
      "sku": null,
      "grams": 0,
      "vendor": "Shopify",
      "taxable": true,
      "product_id": 388319892,
      "product_has_only_default_variant": false,
      "gift_card": false,
      "url": "/products/gray-fedora?variant=794864101",
      "featured_image": {
        "url": "http://cdn.shopify.com/s/files/1/0040/7092/products/gray-fedora.jpeg?v=1402604885",
        "aspect_ratio": 1.0,
        "alt": "Gray fedora made of straw"
      },
      "image": "http://cdn.shopify.com/s/files/1/0040/7092/products/gray-fedora.jpeg?v=1402604885",
      "handle": "gray-fedora",
      "requires_shipping": true,
      "product_title": "Gray Fedora",
      "product_description": "A gray hat for looking cool!",
      "product_type": "Hats",
      "variant_title": "Gray",
      "variant_options": ["Gray"],
      "options_with_values": [
        {
          "name": "Color",
          "value": "Gray"
        }
      ],
      "line_level_discount_allocations": [
        {
          "amount": 500,
          "discount_application": {
            "type": "script",
            "key": "a8a3d7aa-7d00-4827-a2e1-b03c32160bf2",
            "title": "5 Dollar Off",
            "description": null,
            "value": "5.00",
            "created_at": "2019-04-10T20:49:10.023Z",
            "value_type": "fixed_amount",
            "allocation_method": "one",
            "target_selection": "explicit",
            "target_type": "line_item",
            "total_allocated_amount": 500
          }
        }
      ]
    }
  ],
  "requires_shipping": true,
  "currency": "CAD",
  "items_subtotal_price": 18200,
  "cart_level_discount_applications": [
    {
      "type": "automatic",
      "key": "059b5e54-3c5d-4e7e-b377-8e09d8376269",
      "title": "50% Summer Deal",
      "description": null,
      "value": "50.0",
      "created_at": "2019-04-10T20:49:00.148Z",
      "value_type": "percentage",
      "allocation_method": "across",
      "target_selection": "all",
      "target_type": "line_item",
      "total_allocated_amount": 9100
    }
  ]
}

Example response for an empty cart:

{
  "token": "1d19a32178501c44ef2223d73c54d16d",
  "note": null,
  "attributes": {},
  "total_price": 0,
  "total_weight": 0,
  "item_count": 0,
  "items": [],
  "requires_shipping": false,
  "currency": "CAD"
}

POST /cart/update.js

Use this to update the cart's note, attributes, or line item quantities.

POST data

You can submit a serialized cart form, or submit separate updates to a cart's line items, attributes, and note.

Updating line items

Post an updates object with key-value pairs. The key is the line item's variant_id.

jQuery.post('/cart/update.js', {
  updates: {
    794864053: 2,
    794864233: 3
  }
});

This post will yield the same result:

jQuery.post('/cart/update.js',
  "updates[794864053]=2&updates[794864233]=3"
);

The /cart/update.js controller will add 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, the first matching line item will be updated.

You can update a single line item when there are multiple line items in the cart. For example, the following post will update the quantity of only variant 794864053 to 5:

jQuery.post('/cart/update.js', {updates: {794864053: 5}});

Finally, you can remove both variant 794864053 and variant 794864233 from the cart with the following:

jQuery.post('/cart/update.js', {updates: {794864053: 0, 794864233: 0}});

You can also submit an array of numbers to /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:

jQuery.post('/cart/update.js', {updates: [3, 2, 1]});
Updating cart notes

Post a note character string.

The following is an example of post data for a note:

{
  note: 'This is a note about my order'
}
Updating cart attributes

Post an attributes object with key-value pairs. The key is the name of the attribute you want to update.

You can add a double underscore (__) prefix to an attribute name to make it private. Private attributes behave like other cart attributes except that they can't be read from Liquid or the Ajax API. You can use them for data that doesn't affect the page rendering, which allows for more effective page cacheing.

The following is an example of post data for cart attributes:

{
  attributes: {
    'Gift wrap': 'Yes'
  }
}

This version will yield the same result:

  jQuery.post('/cart/update.js', "attributes[Gift wrap]=Yes");
}

Response

The JSON of the cart.

Error responses

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:

{
  "status": 404,
  "message": "Cart Error"
  "description": "Cannot find variant"
}

When a new variant is added to the cart and the quantity exceeds what's available, the result is a 422 error:

{
  "status": 422,
  "message": "Cart Error",
  "description": "You can only add 8 Messenger Bag to the cart."
}

POST /cart/change.js

This call sets the quantity of an item already in the cart. The /cart/change.js controller is only able to update the quantity of one item at a time.

POST data

{
  quantity: 1,
  id: 794864053
}

The quantity is the new quantity you want for a particular item, and id is the variant_id of that line item or the line item's key.

A cart can have multiple line items that share the same id when variants have different line item properties. To account for this, it is recommended to 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 following will update the first item in the cart:

{
  line: 1,
  quantity: 3
}

Response

The JSON of the cart.

jQuery.post('/cart/change.js', { quantity: 1, line: 2 });

Error responses

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

POST /cart/clear.js

This call sets all quantities of all line items in the cart to zero.

Response

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

Example:

{
  "token": "1d19a32178501c44ef2223d73c54d16d",
  "note": null,
  "attributes": {},
  "total_price": 0,
  "total_weight": 0,
  "item_count": 0,
  "items": [],
  "requires_shipping": false
}

GET /cart/shipping_rates.json

Get estimated shipping rates.

Example call:

/cart/shipping_rates.json?shipping_address%5Bzip%5D=K1N+5T2&shipping_address%5Bcountry%5D=Canada&shipping_address%5Bprovince%5D=Ontario

Response

Example:

{
  "shipping_rates": [
    {
      "name": "Ground Shipping",
      "price": "8.00",
      "delivery_date": null,
      "source": "shopify"
    },
    {
      "name": "Expedited Shipping",
      "price": "15.00",
      "delivery_date": null,
      "source": "shopify"
    },
    {
      "name": "Express Shipping",
      "price": "30.00",
      "delivery_date": null,
      "source": "shopify"
    }
  ]
}

On this page