Create Compare Item

Add a product to the authenticated customer's comparison list.

Endpoint

POST /api/shop/compare_items

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	Customer Bearer token (Bearer <accessToken>)

Request Body

{
  "productId": 1
}

Field	Type	Required	Description
productId	integer	Yes	ID of the product to add to the compare list.

Response Fields (201 Created)

The created comparison row. Product and customer come back as path references, not nested objects — no product details are included.

Field	Type	Description
id	integer	New comparison row ID. Keep it for Delete.
product	string	Path of the compared product, e.g. /api/shop/products/126.
customer	string	Path of the owning customer.
createdAt / updatedAt	string	ISO 8601 timestamps.

Behaviour

• Adding a product that is already on the list is rejected with 400; it is not a silent no-op, and there is no toggle endpoint here as there is for the wishlist.
• The list is not channel-scoped, so an item added on one channel appears on all of them.
• Any product type can be added; comparison reads the products separately, so no option choices are stored.

Use Cases

• "Add to compare" on a product card — post the product ID and keep the returned row ID so the same control can remove it again.
• Build a comparison set before rendering — add each product as it is marked, then fetch all of them at once for the comparison table.

Best Practices

• Handle 400 as "already added" — the message names that case explicitly, and it is the common outcome of a double tap.
• Do not render from this response — it carries no name, price, or attributes.
• Cap the set client-side — the API imposes no limit, and a comparison table with a dozen columns is unusable.

Related Resources

• Get Compare Items — the customer's comparison rows
• Delete Compare Item — remove one comparison row
• Delete All Compare Items — clear the whole comparison list