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: ```ssh 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](/docs/storefronts/headless/building-with-the-storefront-api/getting-started) for guidance on getting set up to make requests. ## Create 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. ### Deprecated: Checkout API's `checkoutCreate` ```graphql mutation checkoutCreate($input: CheckoutCreateInput!) { checkoutCreate(input: $input) { checkout { id webUrl lineItems(first: 5) { edges { node { title quantity } } } } } } ``` ```json { "input": { "lineItems": [ { "variantId": "gid://shopify/ProductVariant/1", "quantity": 1 } ] } } ``` ### New: Storefront Cart API's `cartCreate` ```graphql mutation cartCreate($cartInput: CartCreateInput!) { cartCreate(input: $cartInput) { cart { id checkoutUrl lines(first: 5) { edges { node { merchandise { ... on ProductVariant { title } } quantity } } } } } } ``` ```json { "cartInput": { "lines": [ { "quantity": 3, "merchandiseId": "gid://shopify/ProductVariant/42567741931576" # The variant ID added to the cart } ] } } ``` ### Deprecated: Checkout API error handling In the Checkout API, to handle errors you requested `checkoutUserErrors`: ```graphql { checkoutUserErrors { code field message } } ``` ### New: 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: ```graphql { userErrors { field message } } ``` ## Update 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: - [`cartLinesUpdate`](/docs/api/storefront/latest/mutations/cartLinesUpdate) - [`cartLinesAdd`](/docs/api/storefront/latest/mutations/cartLinesAdd) - [`cartLinesRemove`](/docs/api/storefront/latest/mutations/cartLinesRemove) The `cartLinesUpdate` mutation behaves similarly to [`checkoutLineItemsReplace`](/docs/api/storefront/latest/mutations/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. ### Deprecated: Checkout API's `checkoutLineItemsReplace` ```graphql mutation checkoutLineItemsReplace($checkoutId: ID!, $lineItems: [CheckoutLineItemInput!]!) { checkoutLineItemsReplace(checkoutId: $checkoutId, lineItems: $lineItems) { checkout { id lineItems(first:2) { edges { node { id title quantity } } } } } } ``` ```json { "checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4", "lineItems": [ { "variantId": "gid://shopify/ProductVariant/2", "quantity": 1 }, { "variantId": "gid://shopify/ProductVariant/1", "quantity": 1 } ] } ``` ### New: Storefront Cart API's `cartLinesUpdate` ```graphql 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 } } } } } } } } ``` ```json { "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. ### Deprecated: Checkout API's `checkoutDiscountCodeApplyV2` With the Checkout API, discount codes aren't stackable: ```graphql 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 } } } } } } } } ``` ```json { "checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4", "discountCode": "DISCOUNT_CODE" } ``` ### New: Storefront Cart API's `cartDiscountCodesUpdate` The Storefront Cart API supports stackable discount codes. The [`discountCodes`](/docs/api/storefront/2024-04/mutations/cartDiscountCodesUpdate#argument-discountcodes) field in the `cartDiscountCodesUpdate` mutation is an array, which enables you to apply multiple discount codes to the cart: ```graphql mutation cartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]) { cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) { cart { discountCodes { code applicable } discountAllocations { discountedAmount { amount } } cost { subtotalAmount { amount } } } } } ``` ```json { "cartId": "gid://shopify/Cart/c1-d32d27707d68a0d7c599f60d649af6c2", "discountCodes": ["DISCOUNT_CODE", "DISCOUNT_CODE_2"] } ``` ## Associate a customer The Storefont Cart API provides a straightforward way to attach both anonymous and authenticated buyer information to the cart using the [`cartBuyerIdentityUpdate`](/docs/api/storefront/latest/mutations/cartBuyerIdentityUpdate) mutation. The following examples compare updating a shipping address using the Checkout API and the Storefront Cart API. ### Deprecated: Checkout API's `checkoutShippingAddressUpdateV2` ```graphql mutation checkoutShippingAddressUpdateV2($shippingAddress: MailingAddressInput!, $checkoutId: ID!) { checkoutShippingAddressUpdateV2(shippingAddress: $shippingAddress, checkoutId: $checkoutId) { checkout { id shippingAddress { lastName firstName address1 province country zip city } } } } ``` ```json { "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" } ``` ### New: 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`](/docs/api/storefront/latest/mutations/cartBuyerIdentityUpdate) mutation. As of `2025-01`, delivery addresses can be managed using the new cart delivery mutations: - [`cartDeliveryAddressesAdd`](/docs/api/storefront/latest/mutations/cartDeliveryAddressesAdd) - [`cartDeliveryAddressesUpdate`](/docs/api/storefront/latest/mutations/cartDeliveryAddressesUpdate) - [`cartDeliveryAddressesRemove`](/docs/api/storefront/latest/mutations/cartDeliveryAddressesRemove) > Note: > If addresses are provided, they will be prefilled at checkout if the shop is using [Shopify Extensions in Checkout](/docs/apps/build/checkout). You can retrieve the access token using either the [`customerAccessTokenCreate`](/docs/api/storefront/2024-04/mutations/customerAccessTokenCreate) or [`customerAccessTokenCreateWithMultipass`](/docs/api/storefront/latest/mutations/customerAccessTokenCreateWithMultipass) mutations. ### Deprecated: Checkout API's `checkoutCustomerAssociateV2` ```graphql mutation associateCustomerWithCheckout($checkoutId: ID!, $customerAccessToken: String!) { checkoutCustomerAssociateV2(checkoutId: $checkoutId, customerAccessToken: $customerAccessToken) { checkout { id } customer { id } } } ``` ```json { "checkoutId": "gid://shopify/Checkout/1ff620dbf36a96d94eda2bf16b726a05?key=1d4737bf2ed1792b3ef556ad6a33a3b4", "customerAccessToken": "your-customer-access-token" } ``` ### New: Storefront Cart API's `cartBuyerIdentityUpdate` ```graphql mutation cartBuyerIdentityUpdate($cartId: ID!, $buyerIdentityInput: CartBuyerIdentityInput!) { cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentityInput) { cart { id buyerIdentity { email phone countryCode customer { id } } } } } ``` ```json { "cartId": "gid://shopify/Cart/c1-d32d27707d68a0d7c599f60d649af6c2", "buyerIdentityInput": { "accessToken": "your-customer-access-token" } } ``` ## Complete the checkout In the Checkout API, you complete the checkout by retrieving the checkout web URL from the `Checkout` object's [`webUrl`](/docs/api/storefront/latest/objects/Checkout#field-checkout-weburl) field. In the Storefront Cart API, you can retrieve the [`checkoutUrl`](/docs/api/storefront/2024-01/objects/Cart#field-cart-checkouturl) from the `Cart` object at any point in the flow to send the buyer to the Shopify web checkout. ### Deprecated: Checkout API's `webURL` ```graphql query { node(id:"Z2lkOi8vc2hvcGlmeS9DaGVja291dC81ZDliYTZjOTlhNWY4YTVhNTFiYzllMzlmODEwNTNhYz9rZXk9NWIxZTg5NDQzNTZkMjMxOGU1N2ZlNjQwZDJiNjY1M2Y=" ) { ... on Checkout { id webUrl } } } ``` ### New: Storefront Cart API's checkoutURL ```graphql query { cart(id: "gid://shopify/Cart/1") { checkoutUrl } } ``` ## Next 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.