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
Anchor link to section titled "Requirements"- You've reviewed and met the requirements that are listed on the Querying data with the Storefront API page.
- You've created products and product variants in your store.
- You're using version 2022-07 or higher of the Storefront API.
Limitations
Anchor link to section titled "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.
- Duties won't be displayed on cart, but only at checkout. Taxes are available to display on a cart.
Considerations
Anchor link to section titled "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 10 days after creation by Shopify.
- Shopify automatically deletes the cart when the customer completes their checkout.
- Shopify Plus bot protection is available for cart.
How a cart works
Anchor link to section titled "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:
| 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. Estimated costs are subject to change and changes are reflected 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. |
International pricing
Anchor link to section titled "International pricing"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:
- Checkout pricing: The final sale price.
BuyerIdentityis used to determine international pricing and should match the customer's shipping address. - Cart pricing: The estimated final sale price.
EstimatedCostusesBuyerIdentityto determine international pricing. - Product queries: The price that displays on a product page. Products use the
@inContextdirective to determine international pricing.
Create a cart and add a line item
Anchor link to section titled "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:
cost: 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
Anchor link to section titled "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:
Increase an item's quantity
Anchor link to section titled "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.
Update customer information
Anchor link to section titled "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.
Retrieve a checkout URL
Anchor link to section titled "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.