API reference navigation

Storefront Wishlist

Storefront

Storefront Wishlist groups 4 operations on the storefront tier.

Storefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

GET

/api/{version}/wishlist

The visitor's saved products, newest first. Returns an empty list (200) rather than 404 when nothing has been saved. Paged with limit/offset; item_count is always the full total.

AuthenticationAnonymousStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Query parameters

Name	Type	Description
limit optional	integer (int32)	Page size. Clamped to 1..250 by the handler.
offset optional	integer (int32)	Rows to skip, newest saved first.

Responses

200StorefrontWishlistResponseOK

curl -X GET \
  'https://<your-shop-domain>/api/2026-04-01/wishlist' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Response200example shape

{
  "wishlist": {
    "item_count": 1,
    "items": [
      {
        "product_id": "00000000-0000-0000-0000-000000000000",
        "added_at": "2026-04-01T12:00:00Z",
        "product": {}
      }
    ]
  }
}

DELETE

/api/{version}/wishlist

Unsave everything. Idempotent; returns the now-empty list (200).

AuthenticationAnonymousStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Responses

200StorefrontWishlistResponseOK

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/wishlist' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Response200example shape

{
  "wishlist": {
    "item_count": 1,
    "items": [
      {
        "product_id": "00000000-0000-0000-0000-000000000000",
        "added_at": "2026-04-01T12:00:00Z",
        "product": {}
      }
    ]
  }
}

POST

/api/{version}/wishlist/items

{ product_id } — save a product. Idempotent: saving one that is already on the list returns the unchanged list. 422 when product_id is not a published product of this shop.

AuthenticationAnonymousStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Request body

application/json, text/json, application/*+json · optional

StorefrontWishlistAddItemRequest

Body for POST /wishlist/items — the product to save.

product_idstring (uuid)required
The product (not variant) id to save.

Responses

200StorefrontWishlistResponseOK
422ApiErrorResponseUnprocessable Content

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/wishlist/items' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "product_id": "00000000-0000-0000-0000-000000000000"
}'

Response200example shape

{
  "wishlist": {
    "item_count": 1,
    "items": [
      {
        "product_id": "00000000-0000-0000-0000-000000000000",
        "added_at": "2026-04-01T12:00:00Z",
        "product": {}
      }
    ]
  }
}

DELETE

/api/{version}/wishlist/items/{id}

Unsave a product ({id} is the product Guid). Returns the updated list (200); idempotent for a product that is not on the list.

AuthenticationAnonymousStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Path parameters

Name	Type	Description
id required	string (uuid)

Responses

200StorefrontWishlistResponseOK

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/wishlist/items/<id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Response200example shape

{
  "wishlist": {
    "item_count": 1,
    "items": [
      {
        "product_id": "00000000-0000-0000-0000-000000000000",
        "added_at": "2026-04-01T12:00:00Z",
        "product": {}
      }
    ]
  }
}

Schemas

ApiErrorResponse

The error envelope every non-2xx response from this API uses. Documentation shape: actions build it as an anonymous object, so this type exists to give the OpenAPI document a schema to point at.

errorsstringnullable
Human-readable description of what went wrong, e.g. Not Found, Invalid page_info.
codestringnullable
Machine-readable error code. Only a few endpoints (checkout) emit one; omitted everywhere else.

StorefrontCustomFieldDto

Storefront custom field: a tenant-defined attribute (key, localized label, value, kind).

keystringnullable
labelstringnullable
valuestringnullable
typestringnullable

StorefrontFacetRefDto

One facet value: the id to filter by and its localized label. name is null while the tenant's periodically-rebuilt filter snapshot doesn't yet carry the id — membership is still reported.

idstring (uuid)
namestringnullable

StorefrontFlagDto

Storefront product badge/flag: display name and CSS colour.

namestringnullable
colorstringnullable

StorefrontManufacturerDto

Storefront manufacturer (vendor): id, display name, logo URL.

idstring (uuid)
namestringnullable
logo_urlstringnullable

StorefrontProductDto

Storefront representation of a catalog product. This is the list projection: it carries the product's gross retail price range (price_min/price_max in currency) and variant count so a listing/collection card can show a price range and an "N options" badge, mirroring a Shopify storefront listing. The full variant list is served by the detail read and /{id}/variants.

idstring (uuid)
handlestringnullable
titlestringnullable
body_htmlstringnullable
imagestringnullable
availableboolean
currencystringnullable
price_minnumber (double)
Lowest variant gross price; 0 when the product has no priced variant.
price_maxnumber (double)
Highest variant gross price; 0 when the product has no priced variant.
variants_countinteger (int32)
Number of active, published variants.
manufacturerStorefrontManufacturerDto
flagStorefrontFlagDto
ratingnumber (double)
Average approved rating (0 when unrated).
rating_countinteger (int32)
Number of approved ratings.
custom_fieldsStorefrontCustomFieldDto[]nullable
Tenant-defined custom attributes for the representative variant.
variantsStorefrontVariantDto[]nullable
The product's variants (list-level view from the catalog index). Tax rate, alcohol volume and option group are not carried by the index and are left at their defaults here; the single-product detail read returns the fully-resolved variants. For a text search only matching variants appear — see Cloudwawi.Shop.Api.V2026_04_01.Storefront.StorefrontProductDto.VariantsCount for the true total.

StorefrontQuantityRuleDto

Storefront variant quantity rule: minimum, optional maximum, and increment (step).

minnumber (double)
maxnumber (double)nullable
incrementnumber (double)

StorefrontVariantDto

Storefront representation of a product variant, including the product attributes the storefront page renders. Money fields are in the enclosing response's currency — Cloudwawi.Shop.Api.V2026_04_01.Storefront.StorefrontProductDetailDto.Currency on the detail read, the sibling currency field on the /{id}/variants envelope.

idstring (uuid)
product_idstring (uuid)
handlestringnullable
titlestringnullable
skustringnullable
option_groupstringnullable
pricenumber (double)
Display price (gross, tax included).
net_pricenumber (double)
compare_at_pricenumber (double)
Pre-discount price when on offer; 0 otherwise.
tax_ratenumber (double)
availableboolean
inventory_quantitynumber (double)
descriptionstringnullable
description_additionalstringnullable
yearstringnullable
sizestringnullable
areastringnullable
countrystringnullable
alcohol_volumenumber (double)nullable
quantity_ruleStorefrontQuantityRuleDto
custom_fieldsStorefrontCustomFieldDto[]nullable
Tenant-defined custom attributes for this variant.
factsheet_urlstringnullable
Relative URL of the generated variant factsheet PDF.
facetsStorefrontVariantFacetsDto

StorefrontVariantFacetsDto

A variant's facet membership. Each entry pairs the filter token a client sends back with its localized label, so a card can render attribute chips and a client can filter in-memory without a second call.

colorStorefrontFacetRefDto
regionStorefrontFacetRefDto
vintageStorefrontFacetRefDto
sizeStorefrontFacetRefDto
optionsStorefrontVariantOptionDto[]nullable
Tenant-defined dropdown options (grape variety, for tenants that model it). Each carries the owning field's field_key so a client can select the field it cares about.

StorefrontVariantOptionDto

A selected tenant-defined option, qualified by the custom field that owns it.

field_keystringnullable
Stable machine key of the owning custom field (falls back to its numeric code).
field_labelstringnullable
Localized display name of the owning custom field.
idstring (uuid)
namestringnullable

StorefrontWishlistAddItemRequest

Body for POST /wishlist/items — the product to save.

product_idstring (uuid)required
The product (not variant) id to save.

StorefrontWishlistDto

Storefront representation of the visitor's wishlist. item_count is the total number of saved products, which exceeds items.length when the read is paged or when a saved product is no longer published.

item_countinteger (int32)
itemsStorefrontWishlistItemDto[]nullable

StorefrontWishlistItemDto

Versioned (2026-04-01) representation of a saved product. product_id is the id used to address the entry in DELETE /wishlist/items/{id}, and product is the same projection GET /products returns, so a wishlist page needs no follow-up catalog calls.

product_idstring (uuid)
added_atstring (date-time)
When the visitor saved this product.
productStorefrontProductDto

StorefrontWishlistResponse

Envelope returned by every action on /wishlist — GET /wishlist, POST /wishlist/items, DELETE /wishlist/items/{id} and DELETE /wishlist. As with the cart, each action returns the full list after the change. The list is resolved from the request identity rather than an id in the route, and the write actions are idempotent: saving a product that is already saved, or removing one that is not on the list, returns the unchanged list with 200.

wishlistStorefrontWishlistDto