Wishlist actions

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.

product_id Required: Product to save.
variant_id Optional: Specific variant to save.
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.

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

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

{
  success,
  wishlist,
  user_errors
}

POST /wishlist/clear

{% form 'wishlist_clear' %}

Empties the wishlist.

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.

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

No action-specific numeric limit.

{
  success,
  wishlist,
  user_errors
}

POST /wishlist/remove

{% form 'wishlist_remove' %}

Removes the saved product.

product_id Required: Product to remove.
variant_id Optional: Specific saved variant.
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.

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

No action-specific numeric limit.

{
  success,
  wishlist,
  user_errors
}

POST /wishlist/toggle

{% form 'wishlist_toggle' %}

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

product_id Required: Product to toggle.
variant_id Optional: Specific variant to toggle.
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.

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

Merchant-configured wishlist_max_items applies when toggle adds an item.

{
  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.