Manage a cart with the Storefront API
A cart contains the merchandise that a customer intends to purchase, and the estimated cost associated with the cart. You can use the Storefront API to interact with a cart during a customer's session.
This tutorial shows how to create a cart and retrieve it, update cart line items and customer information, and retrieve a checkout URL.
- You've reviewed and met the requirements that are listed on the Getting started with the Storefront API page.
- You've created products and product variants in your store.
- If you're using the checkout workflow to manage a cart and want to adopt the cart workflow instead, then you need to manually migrate your app.
- Scripts aren't currently supported in a cart, but they're still applied at checkout.
- The cart works with the web checkout only. It isn't supported for native mobile checkouts.
- You need to make products available to the Online Store to work with the cart. This limitation will be removed when the cart functionality becomes available in the 2021-10 API version release.
- The cart is subject to the same throttling restrictions as the Storefront API.
- The cart supports a maximum of 500 line items.
- A shop or customer can create an unlimited number of carts.
- Unused and abandoned carts are auto-expired by Shopify.
- Shopify automatically deletes the cart when the customer completes their checkout.
How a cart works
Customers add items to their cart that they intend to purchase. When a customer is ready to purchase their items, they can proceed to checkout.
The cart object includes the following relationships:
||An object that contains the merchandise that a customer intends to purchase.|
||Identifies the customer that is interacting with the cart. It includes a customer access token that associates the customer with the cart.|
||The estimated total cost of all merchandise that the customer will pay at checkout.|
||An array of custom information for a cart line. Attributes are returned as key-value pairs.|
||A list of line item objects, each containing information about an item in the cart.|
||A product variant. It represents one version of a product with several options.|
Create a cart and add a line item
You can use the
cartCreate mutation to create a new cart and add a line item to the cart. In the input, include the product variant ID (
merchandiseId), include the line item quantity (
quantity) and specify any attributes (
attributes) associated with the cart.
In the response, request the added line item’s ID, merchandise, and attributes to verify that it was added correctly. You can also request information about the costs associated with the cart:
estimatedCost: The estimated total cost of all merchandise that the customer will pay at checkout.
subtotalAmount: The estimated amount, before taxes and discounts, for the customer to pay at checkout.
totalTaxAmount: The estimated tax amount for the customer to pay at checkout.
totalDutyAmount: The estimated duty amount for the customer to pay at checkout.
Retrieve a cart
The following example shows how to retrieve a cart by its ID:
Increase an item's quantity
You can adjust the line item quantity to add another product variant of the same type to the cart using the
In the mutation's input, include the cart ID, cart line ID, and the new quantity value that you want to set. In the response, request the ID and quantity of the line items to verify that it was updated correctly.
The following example shows how to increase a line item's quantity in a cart to three.
Update customer information
You can use the
cartBuyerIdentityUpdate mutation to associate customer information with the cart, such as a customer's email, phone number, and country.
In the mutation's input, supply the cart ID and the
buyerIdentity attributes related to the customer (for example,
countryCode). In the response, request the same information to verify that it was updated correctly.
Retrieve a checkout URL
To retrieve a checkout URL for the current cart, you can query the
cart object and supply the cart's ID as your input. The response includes a URL that, when viewed in a browser, will redirect customers through Shopify’s web checkout workflow.
- Learn how create a cart and a subscription line item.
- Learn how to query international prices for products and orders, and explicitly set the context of a cart and checkout.
- Learn how to manage customer accounts with the Storefront API.
- Learn about the different tools that you can use to create unique buying experiences anywhere your customers are, including websites, apps, and video games.