Merge Cart

About

The createMergeCart mutation merges a guest (unauthenticated) cart into the authenticated customer's cart. This is essential for preserving the shopping experience when a guest user logs in after adding items to their cart. Use this mutation to:

• Transfer guest cart items to the customer's cart after login
• Preserve products added during anonymous browsing
• Combine guest and existing customer cart items seamlessly

How It Works

1. A guest user browses the store and adds items to a cart using the Create Cart mutation, which returns a cartToken and cart _id
2. The guest decides to log in via the Customer Login mutation and receives a Bearer token
3. The createMergeCart mutation is called with the guest cart's _id as cartId and the customer's Bearer token in the Authorization header
4. The system merges all guest cart items into the customer's cart and returns the updated cart state

Authentication

This mutation requires customer authentication. The Bearer token identifies which customer's cart the guest cart should be merged into.

Authorization: Bearer <customerAccessToken>
X-STOREFRONT-KEY: <storefrontKey>

Arguments

Argument	Type	Required	Description
cartId	Int!	Yes	The _id of the guest cart to merge. This is the numeric ID returned by the Create Cart mutation during the guest session.

Response

Field	Type	Description
id	String	The merged cart ID (customer's cart)
itemsCount	Int	Total number of distinct items in the merged cart
grandTotal	Float	Updated grand total of the merged cart
success	Boolean	Whether the merge was successful
message	String	Success or error message

Typical Flow

Guest Session:
  1. createCartToken → get cartToken + cart _id (e.g. 364)
  2. addProductInCart → add items using guest cart token

Login:
  3. createCustomerLogin → get customer Bearer token

Merge:
  4. createMergeCart(cartId: 364) → with customer Bearer token
     → Guest cart items are now in the customer's cart

Note: After a successful merge, the guest cart is invalidated. The cartToken from the guest session can no longer be used. All subsequent cart operations should use the customer's Bearer token.

Related Documentation

• Create Cart — Create a guest cart and get the cart _id
• Add to Cart — Add products to cart
• Get Cart — View the merged cart contents
• Customer Login — Authenticate and get Bearer token