Skip to main content

Migrate your app

The Storefront Cart API is part of the Storefront API, which is a GraphQL API. It's used for building buyer experiences, such as custom storefronts, mobile apps, apps that interact with Cart and Storefront and more. You can access the Storefront Cart API at the following endpoint:

https://your-shop-name.myshopify.com/api/2024-04/graphql.json
Note

To make requests to this API, you'll need to include an X-Shopify-Storefront-Access-Token. Refer to our getting started documentation for guidance on getting set up to make requests.

Anchor to Create a CartCreate a Cart

The Storefront Cart API enables you to assemble a buyer's purchase, providing all relevant details back to the buyer before transitioning into the checkout process. This means you can add, remove, or update items in the cart, apply discounts, and more, before you create the checkout. Modifying a cart instead of a checkout provides your application a more feature-rich and performant way of assembly.

Anchor to Deprecated: Checkout API's ,[object Object]Deprecated: Checkout API's checkoutCreate

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Checkout API

mutation checkoutCreate($input: CheckoutCreateInput!) {
checkoutCreate(input: $input) {
checkout {
id
webUrl
lineItems(first: 5) {
edges {
node {
title
quantity
}
}
}
}
}
}

Input

{
"input": {
"lineItems": [
{
"variantId": "gid://shopify/ProductVariant/1",
"quantity": 1
}
]
}
}

Anchor to New: Storefront Cart API's ,[object Object]New: Storefront Cart API's cartCreate

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Storefront Cart API

mutation cartCreate($cartInput: CartCreateInput!) {
cartCreate(input: $cartInput) {
cart {
id
checkoutUrl
lines(first: 5) {
edges {
node {
merchandise {
... on ProductVariant {
title
}
}
quantity
}
}
}
}
}
}

Input

{
"cartInput": {
"lines": [
{
"quantity": 3,
"merchandiseId": "gid://shopify/ProductVariant/42567741931576" # The variant ID added to the cart
}
]
}
}

Anchor to Deprecated: Checkout API error handlingDeprecated: Checkout API error handling

In the Checkout API, to handle errors you requested checkoutUserErrors:

Errors

{
checkoutUserErrors {
code
field
message
}
}

Anchor to New: Storefront Cart API error handlingNew: Storefront Cart API error handling

With the Storefront Cart API, you request userErrors to receive information about errors that are related to the entire API surface:

Errors

{
userErrors {
field
message
}
}

Anchor to Update a cartUpdate a cart

Updating the cart enables you to adjust the line items, discounts, attributes, notes, and more, before finalizing the cart and sending the buyer to checkout. The Storefront Cart API provides the following main methods for updating line items in the cart:

The cartLinesUpdate mutation behaves similarly to checkoutLineItemsReplace in the Checkout API. It replaces the existing line items in the cart with the new line items provided in the lines argument. This is useful when you want to completely refresh the cart contents.

Anchor to Deprecated: Checkout API's ,[object Object]Deprecated: Checkout API's checkoutLineItemsReplace

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Checkout API

mutation checkoutLineItemsReplace($checkoutId: ID!, $lineItems: [CheckoutLineItemInput!]!) {
checkoutLineItemsReplace(checkoutId: $checkoutId, lineItems: $lineItems) {
checkout {
id
lineItems(first:2) {
edges {
node {
id
title
quantity
}
}
}
}
}
}

Input

{
"checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4",
"lineItems": [
{
"variantId": "gid://shopify/ProductVariant/2",
"quantity": 1
},
{
"variantId": "gid://shopify/ProductVariant/1",
"quantity": 1
}
]
}

Anchor to New: Storefront Cart API's ,[object Object]New: Storefront Cart API's cartLinesUpdate

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Storefront Cart API

mutation cartLinesUpdate($cartId: ID!, $lines: [CartLineInput!]!) {
cartLinesUpdate(cartId: $cartId, lines: $lines) {
cart {
id
checkoutUrl
lines(first: 2) {
edges {
node {
id
quantity
merchandise {
... on ProductVariant {
id
title
}
}
}
}
}
}
}
}

Input

{
"cartId": "gid://shopify/Cart/c1-d32d27707d68a0d7c599f60d649af6c2",
"lines": [
{
"id": "gid://shopify/ProductVariant/2",
"quantity": 1
},
{
"id": "gid://shopify/ProductVariant/1",
"quantity": 1
}
]
}

If you want to add new line items to the existing ones in the cart, you should use cartLinesAdd. This enables you to build up the cart contents incrementally, without discarding the current lines.

Anchor to Deprecated: Checkout API's ,[object Object]Deprecated: Checkout API's checkoutDiscountCodeApplyV2

With the Checkout API, discount codes aren't stackable:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Checkout API

mutation checkoutDiscountCodeApplyV2($checkoutId: ID!, $discountCode: String!) {
checkoutDiscountCodeApplyV2(checkoutId: $checkoutId, discountCode: $discountCode) {
checkout {
totalPriceV2 {
amount
currencyCode
}
discountApplications(first: 5) {
edges {
node {
applicable
value {
... on MoneyV2 {
amount
currencyCode
}
}
}
}
}
}
}
}

Input

{
"checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4",
"discountCode": "DISCOUNT_CODE"
}

Anchor to New: Storefront Cart API's ,[object Object]New: Storefront Cart API's cartDiscountCodesUpdate

The Storefront Cart API supports stackable discount codes. The discountCodes field in the cartDiscountCodesUpdate mutation is an array, which enables you to apply multiple discount codes to the cart:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Storefront Cart API

mutation cartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]) {
cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
cart {
discountCodes {
code
applicable
}
discountAllocations {
discountedAmount {
amount
}
}
cost {
subtotalAmount {
amount
}
}
}
}
}

Input

{
"cartId": "gid://shopify/Cart/c1-d32d27707d68a0d7c599f60d649af6c2",
"discountCodes": ["DISCOUNT_CODE", "DISCOUNT_CODE_2"]
}

Anchor to Associate a customerAssociate a customer

The Storefont Cart API provides a straightforward way to attach both anonymous and authenticated buyer information to the cart using the cartBuyerIdentityUpdate mutation. The following examples compare updating a shipping address using the Checkout API and the Storefront Cart API.

Anchor to Deprecated: Checkout API's ,[object Object]Deprecated: Checkout API's checkoutShippingAddressUpdateV2

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Checkout API

mutation checkoutShippingAddressUpdateV2($shippingAddress: MailingAddressInput!, $checkoutId: ID!) {
checkoutShippingAddressUpdateV2(shippingAddress: $shippingAddress, checkoutId: $checkoutId) {
checkout {
id
shippingAddress {
lastName
firstName
address1
province
country
zip
city
}
}
}
}

Input

{
"shippingAddress": {
"lastName": "Hirano",
"firstName": "Ayumu",
"address1": "151 O'Connor St",
"province": "ON",
"country": "Canada",
"zip": "K2P 2L8",
"city": "Ottawa"
},
"checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4"
}

Anchor to New: Storefront Cart API's ,[object Object], and ,[object Object], mutationsNew: Storefront Cart API's cartBuyerIdentityUpdate and cartDeliveryAddressesAdd mutations

The Storefront Cart API enables you to update the buyer's identity and preferences using the cartBuyerIdentityUpdate mutation. As of 2025-01, delivery addresses can be managed using the new cart delivery mutations:

Note

If addresses are provided, they will be prefilled at checkout if the shop is using Shopify Extensions in Checkout.

You can retrieve the access token using either the customerAccessTokenCreate or customerAccessTokenCreateWithMultipass mutations.

Anchor to Deprecated: Checkout API's ,[object Object]Deprecated: Checkout API's checkoutCustomerAssociateV2

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Checkout API

mutation associateCustomerWithCheckout($checkoutId: ID!, $customerAccessToken: String!) {
checkoutCustomerAssociateV2(checkoutId: $checkoutId, customerAccessToken: $customerAccessToken) {
checkout {
id
}
customer {
id
}
}
}

Input

{
"checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4",
"customerAccessToken": "your-customer-access-token"
}

Anchor to New: Storefront Cart API's ,[object Object]New: Storefront Cart API's cartBuyerIdentityUpdate

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Storefront Cart API

mutation cartBuyerIdentityUpdate($cartId: ID!, $buyerIdentityInput: CartBuyerIdentityInput!) {
cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentityInput) {
cart {
id
buyerIdentity {
email
phone
countryCode
customer {
id
}
}
}
}
}

Input

{
"cartId": "gid://shopify/Cart/c1-d32d27707d68a0d7c599f60d649af6c2",
"buyerIdentityInput": {
"accessToken": "your-customer-access-token"
}
}

Anchor to Complete the checkoutComplete the checkout

In the Checkout API, you complete the checkout by retrieving the checkout web URL from the Checkout object's webUrl field. In the Storefront Cart API, you can retrieve the checkoutUrl from the Cart object at any point in the flow to send the buyer to the Shopify web checkout.

Anchor to Deprecated: Checkout API's ,[object Object]Deprecated: Checkout API's webURL

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

query {
node(id:"Z2lkOi8vc2hvcGlmeS9DaGVja291dC81ZDliYTZjOTlhNWY4YTVhNTFiYzllMzlmODEwNTNhYz9rZXk9NWIxZTg5NDQzNTZkMjMxOGU1N2ZlNjQwZDJiNjY1M2Y=" ) {
... on Checkout {
id
webUrl
}
}
}

Anchor to New: Storefront Cart API's checkoutURLNew: Storefront Cart API's checkoutURL

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

query {
cart(id: "gid://shopify/Cart/1") {
checkoutUrl
}
}

Anchor to Next stepsNext steps

Explore the Storefront Cart API tutorial

Learn more about building with the Storefront Cart API, and how you can extend a cart's functionality.

Storefront Cart API reference

Consult the Storefront API reference documentation to learn more about the Cart object.

Was this page helpful?