---
title: Migrate your app
description: >-
  Learn how you can migrate your app from the Checkout API to the Storefront
  Cart API by consulting equivalent requests and responses for common use cases.
source_url:
  html: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/migrate-to-cart-api/migrate-your-app
  md: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/migrate-to-cart-api/migrate-your-app.md
---

# 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:

```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](https://shopify.dev/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`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Checkout API

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

## Input

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

### New: Storefront Cart API's `cartCreate`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Storefront Cart API

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

## Input

```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`:

## Errors

```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:

## Errors

```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`](https://shopify.dev/docs/api/storefront/latest/mutations/cartLinesUpdate)

* [`cartLinesAdd`](https://shopify.dev/docs/api/storefront/latest/mutations/cartLinesAdd)

* [`cartLinesRemove`](https://shopify.dev/docs/api/storefront/latest/mutations/cartLinesRemove)

The `cartLinesUpdate` mutation behaves similarly to [`checkoutLineItemsReplace`](https://shopify.dev/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`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Checkout API

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

## Input

```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`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Storefront Cart API

```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
              }
            }
          }
        }
      }
    }
  }
}
```

## Input

```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:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Checkout API

```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
              }
            }
          }
        }
      }
    }
  }
}
```

## Input

```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`](https://shopify.dev/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:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Storefront Cart API

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

## Input

```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`](https://shopify.dev/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`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Checkout API

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

## Input

```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`](https://shopify.dev/docs/api/storefront/latest/mutations/cartBuyerIdentityUpdate) mutation. As of `2025-01`, delivery addresses can be managed using the new cart delivery mutations:

* [`cartDeliveryAddressesAdd`](https://shopify.dev/docs/api/storefront/latest/mutations/cartDeliveryAddressesAdd)
* [`cartDeliveryAddressesUpdate`](https://shopify.dev/docs/api/storefront/latest/mutations/cartDeliveryAddressesUpdate)
* [`cartDeliveryAddressesRemove`](https://shopify.dev/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](https://shopify.dev/docs/apps/build/checkout).

You can retrieve the access token using either the [`customerAccessTokenCreate`](https://shopify.dev/docs/api/storefront/2024-04/mutations/customerAccessTokenCreate) or [`customerAccessTokenCreateWithMultipass`](https://shopify.dev/docs/api/storefront/latest/mutations/customerAccessTokenCreateWithMultipass) mutations.

### Deprecated: Checkout API's `checkoutCustomerAssociateV2`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Checkout API

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

## Input

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

### New: Storefront Cart API's `cartBuyerIdentityUpdate`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## Storefront Cart API

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

## Input

```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`](https://shopify.dev/docs/api/storefront/latest/objects/Checkout#field-checkout-weburl) field. In the Storefront Cart API, you can retrieve the [`checkoutUrl`](https://shopify.dev/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`

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

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

### New: Storefront Cart API's checkout​URL

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

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

***

## Next steps

[Explore the Storefront Cart API tutorial\
\
](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage)

[Learn more about building with the Storefront Cart API, and how you can extend a cart's functionality.](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage)

[Storefront Cart API reference\
\
](https://shopify.dev/docs/api/storefront/latest/objects/cart)

[Consult the Storefront API reference documentation to learn more about the Cart object.](https://shopify.dev/docs/api/storefront/latest/objects/cart)

***