Create Wishlist Item

Add a product to the authenticated customer's wishlist.

Endpoint

POST /api/shop/wishlists

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": 2
}

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

Response Fields (201 Created)

The created wishlist row. Product, customer, and channel come back as path references, not nested objects — the product's name and price are not part of this payload.

Field	Type	Description
id	integer	New wishlist row ID. Keep it for Delete and Move to Cart.
product	string	Path of the saved product, e.g. /api/shop/products/126.
customer	string	Path of the owning customer.
channel	string	Path of the channel the item was saved on.
createdAt / updatedAt	string	ISO 8601 timestamps.

Behaviour

• The row is scoped to the current channel, so the same product can be saved once per channel.
• Adding a product that is already saved is rejected with 400 — it is not a silent no-op. A heart button that must also un-save should call Toggle instead.
• Any product type can be saved, including configurable and bundled ones. Option choices are not stored, which is why those types cannot later be moved straight to the cart.

Use Cases

• "Add to wishlist" on a product page — post the product ID and keep the returned row ID so the same button can remove it again without re-listing.
• Save for later from the cart — add here, then remove the cart line; there is no single endpoint that does both.

Best Practices

• Prefer Toggle for a heart icon — this endpoint only adds, and a second tap produces a 400 the UI has to special-case.
• Do not render from this response — it carries no product name, price, or image; keep the details you already had on screen.
• Treat 403 as "log in first" — guests get no wishlist, so the control should prompt for login rather than retry.

Related Resources

• Get Wishlist Items — the customer's saved products
• Toggle Wishlist Item — add or remove in one call, for a heart icon
• Delete Wishlist Item — remove one saved row by its id