Wishlist

Add, remove, toggle, and clear saved products under the store's customer policy.

POST /wishlist/add

{% form 'wishlist_add' %}

Saves the product; requires wishlist enabled. Guests allowed when the store permits.

Form fields

product_id Required: Product to save.
variant_id Optional: Specific variant to save.
properties[<namespace>.<key>]… Optional: Declared buyer-writable wishlist-line properties.
_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.
client_mutation_id Optional: Unique retry key, up to 128 characters. Reusing it for the same action prevents a successful mutation from being applied twice for 24 hours.

Validation

Positive product/variant ids; wishlist and guest-wishlist policy, ownership, product validity, and login requirements are enforced.

Limits

Merchant-configured wishlist_max_items; default 100, configurable from 1 to 1000.

Response

{
  success,
  wishlist,
  user_errors
}

POST /wishlist/clear

{% form 'wishlist_clear' %}

Empties the wishlist.

Form fields

_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.
client_mutation_id Optional: Unique retry key, up to 128 characters. Reusing it for the same action prevents a successful mutation from being applied twice for 24 hours.

Validation

Requires a valid wishlist owner; wishlist availability and login policy are enforced.

Limits

No action-specific numeric limit.

Response

{
  success,
  wishlist,
  user_errors
}

POST /wishlist/move-to-cart

{% form 'wishlist_move_to_cart' %}

Validates and adds the selected purchasable line, then removes the exact saved row in the same transaction.

Form fields

product_id Required: Saved product to move.
variant_id Optional: Destination variant; required when the product has variants.
wishlist_variant_id Optional: Variant on the saved row. Omit for a product-level saved row.
wishlist_identity_hash Optional: Identity hash of the exact saved row.
quantity Optional: Cart quantity; defaults to 1.
client_mutation_id Optional: Unique retry key, up to 128 characters. Reusing it for the same action prevents a successful mutation from being applied twice for 24 hours.

Validation

The saved row must exist. The destination product, selected variant, quantity, channel visibility, inventory, purchase state, and order limits use the canonical cart validation path.

Limits

Quantity defaults to 1 and uses the cart line quantity limits.

Response

{
  success,
  cart,
  user_errors
}

cart addition and wishlist removal commit atomically.

POST /wishlist/remove

{% form 'wishlist_remove' %}

Removes the saved product.

Form fields

product_id Required: Product to remove.
variant_id Optional: Specific saved variant.
identity_hash Optional: Required to target one exact saved line when it carries properties.
_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.
client_mutation_id Optional: Unique retry key, up to 128 characters. Reusing it for the same action prevents a successful mutation from being applied twice for 24 hours.

Validation

Positive product/variant ids and a valid wishlist owner; removing an absent item is idempotent.

Limits

No action-specific numeric limit.

Response

{
  success,
  wishlist,
  user_errors
}

POST /wishlist/toggle

{% form 'wishlist_toggle' %}

Adds when absent, removes when present — one form for both states.

Form fields

product_id Required: Product to toggle.
variant_id Optional: Specific variant to toggle.
properties[<namespace>.<key>]… Optional: Declared buyer-writable wishlist-line properties used to identify the saved line.
identity_hash Optional: Targets one exact existing saved line when toggling it off.
_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.
client_mutation_id Optional: Unique retry key, up to 128 characters. Reusing it for the same action prevents a successful mutation from being applied twice for 24 hours.

Validation

Same policy and product validation as add; adds when absent and removes when present.

Limits

Merchant-configured wishlist_max_items applies when toggle adds an item.

Response

{
  success,
  wishlist,
  user_errors
}

User error codes#

Code	When
STOREFRONT_WISHLIST_DISABLED	The store has wishlists off — hide the UI via ctx.wishlist.enabled.
STOREFRONT_WISHLIST_LOGIN_REQUIRED	Guest wishlists are off and the visitor isn't logged in (ctx.wishlist.login_required).
STOREFRONT_WISHLIST_MAX_ITEMS	The wishlist is full (ctx.customer_settings.wishlist_max_items).
STOREFRONT_WISHLIST_PRODUCT_INVALID	product_id missing or wrong.
STOREFRONT_WISHLIST_VARIANT_INVALID	variant_id wrong for the product.
STOREFRONT_WISHLIST_OWNER_REQUIRED	No usable visitor session — reload the page.