Wishlist Module — Storefront

HTTP surface for the customer wishlist — one wishlist per customer ("My Wishlist"), keyed at the variant level. The default wishlist is lazy-materialized on first access so the storefront never has to call a "create my wishlist" endpoint. The wishlist itself is invisible on the wire: there is no list id in the URL or response — leaves room for a future multi-list surface at a sibling path without breaking this contract.

Source: api-modules/wishlist/src/controllers/store-wishlist.controller.ts.

This is a customer-only surface — there is no admin or vendor controller. The wishlist module hooks into the cart module for the "add to cart" action; cart errors propagate unchanged.

Conventions

Authentication

Every read and write is scoped to session.user.id. There is no guest wishlist.

Headers

The add-to-cart endpoint accepts the cart module's headers (forwarded verbatim to the cart layer):

Response envelope

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* on the list endpoint */ }
}

Error envelope

Currency

Price fields on WishlistItemResponse (currentPrice, regularPrice, specialPrice) are integer subunits.

Domain types

WishlistItemResponse

type WishlistItemResponse = {
  variantId: string;
  productId: string;
  vendorId: string;
  productName: string;
  variantName: string | null;
  thumbnail: string | null;
  /** Effective unit price (active special if in-window, else regular). Integer subunits. */
  currentPrice: number | null;
  regularPrice: number | null;
  /** Active special unit price, or null if none / outside the window. */
  specialPrice: number | null;
  /** Best-effort live stock signal. `false` reflects present-but-OOS — soft-deleted variants
   *  are filtered out of the response entirely. */
  isInStock: boolean;
  addedAt: string;                          // ISO
};

The shape mirrors the cart-line snapshot fields so storefronts can reuse a single product-card rendering path.

WishlistContainsResponse

type WishlistContainsResponse = {
  membership: Record<string, boolean>;     // keyed by variantId; every requested id is present
};

Endpoints

Base path: /store/wishlist.

GET /store/wishlist — List my wishlist

Paginated. Newest-added first. The default wishlist is materialized on first call. Soft-deleted variants are filtered out of the response (the underlying row stays in case the variant is restored).

Query

Response 200 — paginated WishlistItemResponse[] with metadata: { total, limit, offset, hasMore }.

POST /store/wishlist/items — Add a variant

Idempotent. Adding the same variant again returns the existing entry and does not re-emit wishlist.item.added.

Body

{ "variantId": "01J9..." }

Response 201 — WishlistItemResponse (same hydrated shape as GET /store/wishlist entries — no follow-up fetch needed).

Side effects — emits wishlist.item.added on first add (not on idempotent re-add).

Errors

DELETE /store/wishlist/items/:variantId — Remove a variant

Idempotent — removing an absent variant still returns 204.

Response 204 No Content.

Side effects — emits wishlist.item.removed when a row was actually removed.

DELETE /store/wishlist/items — Clear my wishlist

Removes every item from the caller's wishlist.

Response 204 No Content.

POST /store/wishlist/items/:variantId/add-to-cart — Move a wishlist item into the cart

Delegates to the cart's add-line. The wishlist entry is NOT removed — the customer keeps the variant saved until they explicitly remove it (rationale: "added to cart" doesn't mean "no longer wanted later"). Cart errors (out-of-stock, min/max quantity, vendor disabled, etc.) propagate unchanged.

Path params

Query

Headers

Response 200 — CartResponse (the cart module's full cart shape — see cart.md).

Errors

POST /store/wishlist/contains — Bulk-check membership

Bulk-only — the singular /contains/:variantId form is intentionally absent so a product-listing page rendering N cards hits the server once, not N times. Does NOT lazy-create the default wishlist; if the caller has never wished for anything, every returned key is false.

Body

{ "variantIds": ["01J9...", "01J9..."] }

Response 200

{
  "data": {
    "membership": {
      "01J9aaaa...": true,
      "01J9bbbb...": false
    }
  }
}

Every variantId from the request is present in membership — clients can index without a hasOwnProperty check.

Errors

Related modules

• cart — add-to-cart forwards to the cart's add-line; the response is the cart's CartResponse. See cart.md.
• catalog — variants referenced by variantId come from this module.
• inventory — drives the isInStock signal on each row.