Skip to main content

Replace Cart Items

ReplaceCartItems Mutation

This mutation replaces all existing items in the customer cart with a single simple item. It is ideal for implementing Buy Now behavior from custom landing pages.

Use Cases​

  • Buy Now buttons: Replace any existing cart with the clicked product.
  • Single-product funnels: Ensure the cart contains only the promoted item.
  • Time-limited offers: Force the cart to just the campaign product.

Headers​

You must send the sessionid header so that the correct cart is selected:

{
  "sessionid": "Session_3f6a0f1d-9c4a-4f3e-8f4b-1a2b3c4d5e6f"
}

Input Parameters​

  • $storeId: ID! – The store in which the cart lives.
  • $item: SimpleItemInput!
    • variantId: ID! – Variant that should be the only item in the cart.
    • quantity: Int! – Quantity for this variant.

All previous items in the cart are removed and replaced with this one.

Response Structure​

Returns an updated Cart object:

  • id, sessionId, status, cartStep – Cart metadata.
  • items – Now contains only the provided variant as a CartSimpleItem.
  • receipt – Updated monetary breakdown after replacement.

Example Variables​

{
  "storeId": "Store_cm84j35iy02m001i89iiu2cts",
  "item": {
    "variantId": "ProductVariant_buy_now_001",
    "quantity": 1
  }
}

Implementation Notes​

  • Use this mutation for Buy Now flows instead of manually clearing the cart.
  • Make sure your UI clearly communicates that other cart items will be discarded.
  • Combine with CheckoutCart to send the customer directly to checkout after this mutation.

GraphQL Endpoint​

https://graphql.wuilt.com

Operation: ReplaceCartItems​

Try It Out​

Query​

mutation ReplaceCartItems($storeId: ID!, $item: SimpleItemInput!) {
customerActions(storeId: $storeId) {
  cart {
    replaceCartItemsWithSimpleItem(item: $item) {
      id
      sessionId
      cartStep
      status
      items {
        ... on CartSimpleItem {
          id
          quantity
          price {
            amount
            currencyCode
          }
          product {
            id
            title
            shortDescription
            descriptionHtml
            handle
            images {
              id
              src
              altText
              width
              height
            }
          }
          variant {
            id
            sku
            price {
              amount
              currencyCode
            }
            compareAtPrice {
              amount
              currencyCode
            }
            image {
              id
              src
              altText
              width
              height
            }
          }
        }
      }
      receipt {
        subtotal {
          amount
          currencyCode
        }
        discount {
          amount
          currencyCode
        }
        shipping {
          amount
          currencyCode
        }
        tax {
          amount
          currencyCode
        }
        total {
          amount
          currencyCode
        }
      }
    }
  }
}
}

Query Variables

1
2
3
4
5
6
7

Note: Make sure to change the storeId with your store ID. For guidance on how to get your store ID, reference the Store ID guide.

Authentication​

To use this query, you will need an API key. Click the "API Key" button in the navigation bar to enter your credentials.