Create and update 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 guide shows how to create a cart and retrieve it, update cart line items and customer information, and retrieve a checkout URL.
Requirements
Anchor link to section titled "Requirements"You've completed the Getting started with the Storefront API guide.
You've created products and product variants in your store.
You're using version 2022-10 or higher of the Storefront API. To set metafields on a cart, you need to use version 2023-04 or higher of the Storefront API.
Cart object relationships
Anchor link to section titled "Cart object relationships"Before you start building a cart, we recommend familiarizing yourself with the following API objects and their relationships:
| Object | Description |
|---|---|
| Cart | An object that contains the merchandise that a customer intends to purchase. |
| CartBuyerIdentity | Identifies the customer that is interacting with the cart. It includes a customer access token that associates the customer with the cart. |
| Cost | The estimated costs that the customer will pay at checkout. The costs are subject to change and changes display at checkout. Merchants can configure the prices of products on a per country basis in their Shopify admin. The prices that display on a storefront are determined in the following ways:
|
| 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. |
Step 1: Create a cart and add a line item
Anchor link to section titled "Step 1: 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 line item quantity (quantity) and the product variant ID (merchandiseId), and specify any attributes (attributes) associated with the cart.
If your storefront has context about the buyer that's interacting with the cart (buyerIdentity), then you can also define delivery address preferences (deliveryAddressPreferences) in the mutation's input. Preferences are declarative lists that Shopify can use to accelerate and personalize checkout, and best optimize conversion.
In the response, request the added line item’s ID, merchandise, attributes, and delivery address preferences to verify that all information was added correctly. You can also request information about the costs associated with the cart:
Step 2: Retrieve a cart
Anchor link to section titled "Step 2: Retrieve a cart"You can use the cart query to retrieve a cart stored on Shopify. In the query, supply the cart ID as your input.
The following example shows how to retrieve a cart by its ID:
Step 3: Increase an item's quantity
Anchor link to section titled "Step 3: Increase an item's quantity"You can use the cartLinesUpdate mutation to add another product variant of the same type to the cart.
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:
Step 4: Update customer information
Anchor link to section titled "Step 4: 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.
Step 5: Set metafields on a cart
Anchor link to section titled "Step 5: Set metafields on a cart"Metafields are a flexible way for your app to add and store additional information about a cart. You can create metafields to extend the cart schema with custom values and logic at checkout. For example, you might want to attach custom structured metadata on a cart, and read it from a checkout extension to deliver a customized end-to-end buyer experience.
You can use the cartMetafieldsSet mutation to create and update metafields on a cart. In the mutation's input, supply the cart ID in the ownerId field, and define the parts of the metafield.
Step 6: Retrieve a checkout URL
Anchor link to section titled "Step 6: 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.