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](/docs/api/storefront) 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
- You've completed the [Getting started with the Storefront API](/docs/storefronts/headless/building-with-the-storefront-api/getting-started) guide.
- You've created [products](/docs/api/admin-graphql/latest/objects/product) and [product variants](/docs/api/admin-graphql/latest/objects/productvariant) in your store.
- You're using version 2022-10 or higher of the Storefront API. To [set metafields on a cart](#step-4-set-metafields-on-a-cart), you need to use version 2023-04 or higher of the Storefront API.
## Cart object relationships
Before you start building a cart, we recommend familiarizing yourself with the following API objects and their relationships:
| Object | Description |
|---|---|
| [Cart](/docs/api/storefront/latest/objects/Cart) | An object that contains the merchandise that a customer intends to purchase. |
| [CartBuyerIdentity](/docs/api/storefront/latest/objects/CartBuyerIdentity) | Identifies the customer that is interacting with the cart. It includes a customer access token that associates the customer with the cart, and a set of preferences that can be used to prefill a checkout session. |
| [Cost](/docs/api/storefront/latest/objects/CartCost) | 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:
**Checkout pricing**: The final sale price. `CartBuyerIdentity` is used to determine [international pricing](/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing#create-a-checkout) and should match the customer's shipping address.
**Cart pricing**: The estimated final sale price. `CartCost` uses `CartBuyerIdentity` to determine [international pricing](/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing#create-a-cart).
**Product queries**: The price that displays on a product page. Products use the `@inContext` directive to determine [international pricing](/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing#create-a-cart).
|
| [Attribute](/docs/api/storefront/latest/objects/Attribute) | An array of custom information for a cart line. Attributes are returned as key-value pairs. |
| [CartLine](/docs/api/storefront/latest/objects/CartLine) | A list of line item objects, each containing information about an item in the cart. |
| [Merchandise](/docs/api/storefront/latest/unions/Merchandise) | A product variant. It represents one version of a product with several options. |
## Cart ID
The cart ID consists of a token and a secret key parameter in the form of `?key=`. When you work with any Cart API, you must always provide the full ID.
Example: `gid://shopify/Cart/Z2NwLXVzLWV4YW1wbGU6MDEyMzQ1Njc4OTAxMjM0NTY3ODkw?key=examplekey1234567890`
> Caution:
> You should always treat the `secret` part of the ID as sensitive information, similar to a password. For example, you should never include it in a shareable link or a public page.
The key serves as a verification mechanism for the cart builder, ensuring the protection of the buyer's private data. If you do not include the secret key during a query, the buyer's private details (such as email or address) will be removed from the cart response. Additionally, if you attempt to modify the cart through a mutation without a key, the mutation will fail with an error message indicating the cart does not exist.
## Step 1: Create a cart and add a line item
You can use the [`cartCreate`](/docs/api/storefront/latest/mutations/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`), or preferred delivery method (`deliveryMethod`) in the mutation's input. Preferences are fields that Shopify can use to accelerate and personalize the checkout process, and best optimize conversions.
> Note:
> To use pick-up points as a delivery method preference, a `buyerIdentity.countryCode` is required to ensure the buyer's country matches with the pick-up point country
In the response, request the added line item’s ID, merchandise, attributes, address, and other 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
You can use the [`cart`](/docs/api/storefront/latest/queries/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
You can use the [`cartLinesUpdate`](/docs/api/storefront/latest/mutations/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: Set metafields on a cart
[Metafields](/docs/apps/build/custom-data) 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`](/docs/api/storefront/latest/mutations/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](/docs/apps/build/custom-data#what-are-metafields).
## Step 5: Update customer information and customer preferences for guest checkout journeys
You can use the [`cartBuyerIdentityUpdate`](/docs/api/storefront/latest/mutations/cartBuyerIdentityUpdate) mutation to associate customer information and their checkout preferences with the cart, such as a customer's email, phone number, country, preferred delivery method, and pickup location.
As of the `2025-01` release, `buyerIdentity.deliveryAddressPreferences` is deprecated. Cart delivery addresses can be managed with three new mutations:
- [`cartDeliveryAddressesAdd`](/docs/api/storefront/latest/mutations/cartDeliveryAddressesAdd)
- [`cartDeliveryAddressesUpdate`](/docs/api/storefront/latest/mutations/cartDeliveryAddressesUpdate)
- [`cartDeliveryAddressesRemove`](/docs/api/storefront/latest/mutations/cartDeliveryAddressesRemove)
In the mutation's input, supply the cart ID and the `buyerIdentity` attributes related to the customer (for example, email, phone, and countryCode), along with any preferences for prefilling checkout like preferred delivery method or pickup location. In the response, request the same information to verify it was updated correctly.
## Step 6: Authenticate customer for logged-in checkouts
You can authenticate the customer by setting a valid `customerAccessToken` in the [`cartBuyerIdentityUpdate`](/docs/api/storefront/latest/mutations/cartBuyerIdentityUpdate) mutation or during cart creation. If you append the `customerAccessToken` to the cart, then the buyer will be logged in when they're redirected to checkout.
## Step 7: Retrieve a checkout URL
When the buyer is ready to complete checkout, you can query the [`Cart`](/docs/api/storefront/latest/queries/cart) object for the [`checkoutUrl`](/docs/api/storefront/latest/objects/Cart#field-checkouturl) by supplying the cart's ID as your input. The response includes a URL that redirects customers through Shopify’s web checkout.
>Note: When the customer access token is set on the cart, the obtained checkoutUrl allows the authenticated buyer to navigate to a logged-in checkout experience. For security reasons, the checkoutUrl should be requested when the buyer is ready to navigate to checkout and can be re-requested if it is stale.
> Note:
> To preserve the buyer's logged-in checkout experience, you must include the `Shopify-Storefront-Buyer-IP` header in your Storefront API call when making server side requests. For more information, refer to [Making server-side requests](/docs/api/usage/authentication#making-server-side-requests).
## Next steps
- Learn how to use the [warnings return field](/docs/storefronts/headless/building-with-the-storefront-api/cart/cart-warnings) to manage automatic changes to your cart.
- Learn how [create a cart and a subscription line item](/docs/storefronts/headless/building-with-the-storefront-api/products-collections/subscriptions#step-4-create-a-cart-and-a-subscription-line-item).
- Learn how to query [international prices](/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing) for products and orders, and explicitly set the context of a cart and checkout.
- Learn how to [manage customer accounts](/docs/storefronts/headless/building-with-the-storefront-api/customer-accounts) with the Storefront API.
- Learn about the [different tools](/docs/storefronts/headless/additional-sdks) that you can use to create unique buying experiences anywhere your customers are, including websites, apps, and video games.
- Learn how to use `@defer` to [fetch carrier-calculated rates](/docs/storefronts/headless/building-with-the-storefront-api/defer#fetching-carrier-calculated-rates-for-the-cart-using-defer) for the cart.
