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.

Requirements

Limitations

  • 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.

Considerations

  • 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:

Diagram showing the Cart API objects

Object Description
Cart An object that contains the merchandise that a customer intends to purchase.
BuyerIdentity Identifies the customer that is interacting with the cart. It includes a customer access token that associates the customer with the cart.
EstimatedCost The estimated total cost of all merchandise that the customer will pay at checkout.
Attribute An array of custom information for a cart line. Attributes are returned as key-value pairs.
CartLine A list of line item objects, each containing information about an item in the cart.
Merchandise 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.

POST /api/2021-10/graphql.json

Variables

View response

JSON response

Retrieve a cart

To retrieve a cart stored on Shopify, supply the cart ID as your input. Make sure that you're aware of the limitations and considerations associated with retrieving a cart.

The following example shows how to retrieve a cart by its ID:

POST /api/2021-10/graphql.json

View response

JSON response

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 cartLineQuantityUpdate mutation.

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.

POST /api/2021-10/graphql.json

Variables

View response

JSON response

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, email, phone, and countryCode). In the response, request the same information to verify that it was updated correctly.

POST /api/2021-10/graphql.json

Variables

View response

JSON response

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.

POST /api/2021-10/graphql.json

Next steps