Merge Cart

Merge a guest cart into the authenticated customer's cart. This is used when a shopper adds items to a cart as a guest and then logs in — the guest cart's items are moved into the customer's own cart so nothing is lost.

Endpoint

POST /api/shop/merge-carts

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	The customer Bearer token (from customer login) — not the cart token

Request Body

{
  "cart_id": 6884
}

Field	Type	Required	Description
cart_id	integer	Yes	The id of the guest cart to merge into the customer cart

How the merge works

1. Auth is required — the request must carry a customer Bearer token. A guest (no token) is rejected with 401.
2. The guest cart is looked up by cart_id — an unknown id returns 404.
3. The items are merged into the customer's active cart (one is created if the customer has none):
   • An item already in the customer cart with the same product and type has its quantities added together.
   • Any other item is copied into the customer cart (a configurable product's selected-variant child is copied too).
4. The guest cart is deactivated after the merge.
5. Invalid items are pruned (a deleted product, or a configurable item missing its variant), then totals are recalculated.
6. The response is the full, up-to-date customer cart.

Response Fields (201 Created)

Field	Type	Description
id	integer	The merged (customer) cart id
cartToken	string	Cart token identifier
customerId	integer	Owner customer id
channelId	integer	Sales channel id
itemsCount	integer	Distinct item count
itemsQty	integer	Total quantity across items
items	array	The merged line items
subtotal	decimal	Subtotal before tax and discount
grandTotal	decimal	Final total
taxAmount	decimal	Tax total
discountAmount	decimal	Discount total
couponCode	string | null	Applied coupon, if any
formattedSubtotal	string	Subtotal with currency symbol
formattedGrandTotal	string	Grand total with currency symbol
success	boolean	Whether the merge succeeded
message	string	Result message

Notes

• Send the customer token, not the guest cart token — the guest cart is identified by the cart_id in the body.
• After a successful merge the guest cart is inactive; continue with the returned customer cart through checkout.

Related Resources

• Create Cart
• Get Cart
• Cart workflow