Skip to content

Merge a guest cart into the signed-in shopper's cart

POST
/stores/{storeRef}/cart/merge
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/cart/merge \
--header 'Authorization: Bearer <token>' \
--header 'x-storefront-api-key: <x-storefront-api-key>'

Call this right after a visitor signs in, with the x-session-id they used for the guest cart. The guest cart’s lines are added to the shopper’s cart, summing quantities for the same product and variant, and the guest cart is retired. When the shopper has no cart, the guest cart becomes theirs. Without the header, or when the guest cart is gone, the shopper’s existing cart is returned as it is; when there is no cart at all the response is { "merged": false }. The cart returned here carries stored lines without prices: read the cart for priced lines.

storeRef
required
string

The store’s ref, as returned by GET /stores.

x-session-id
string

The guest session ID the visitor used with the guest cart routes.

The shopper’s cart after the merge, or { "merged": false } when there is nothing to merge.

Media typeapplication/json
One of:
object
status
required

Cart status.

string
Allowed values: ACTIVE ABANDONED CONVERTED
items
required

The cart’s lines.

Array<object>
object
id

Cart line ID.

string
cart_id

ID of the cart the line belongs to.

string
product_id
required

ID of the product.

number
variant_id

ID of the variant, or null when the line has none.

number
nullable
quantity
required

Units in the line.

number
created_at

When the line was added, as an ISO 8601 timestamp.

string
updated_at

When the line last changed, as an ISO 8601 timestamp.

string
id

Cart ID.

string
user_id

ID of the signed-in shopper who owns the cart, or null for a guest cart.

string
nullable
session_id

The guest session ID that owns the cart, or null once a shopper owns it.

string
nullable
expires_at

When the cart expires, as an ISO 8601 timestamp, or null when it does not.

string
nullable
created_at

When the cart was created, as an ISO 8601 timestamp.

string
updated_at

When the cart last changed, as an ISO 8601 timestamp.

string

Example

{
"status": "ACTIVE"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}