Wishlist & Reviews

Wishlist

Wishlist requires a logged-in customer (client.auth.login first); all calls run with the customer's access token.

Get Wishlist

const { data, error } = await client.wishlist.get();
// data.items: [{ id, productId, productName, productSku, productSlug,
//                imageUrl, price, stockCached, createdAt }]

Add Product

await client.wishlist.add('product-id');

Remove Product

await client.wishlist.remove('product-id');

Check if in Wishlist

const { inWishlist } = await client.wishlist.isInWishlist('product-id');

Product Reviews

Get Reviews

const { data, error } = await client.reviews.getProductReviews('product-id', 1, 20);
// data: { reviews, total, page, limit, averageRating, reviewCount }

The first page must be fetched on the server. Pass the returned data to useProductReviews(productId, {page: 1, limit: 20, initialData}) so the first HTML contains the approved reviews and a real empty state when appropriate. Do not convert an API error into an empty review list. Later pages may load after a click; provide an error and retry state. The hook includes both page and limit in its query key.

Pages start at 1, the maximum page is 1,000,000, and limit is 1 to 100. Disabled products and products outside a domain's curated catalog return 404. A published parent selected for that domain permits its own variant reviews. Render the returned photos as safe public links, the merchant reply, verified badge, localized date and aggregate. A selected variant has its own product ID, ratingAverage and ratingCount; never reuse another listing's reviews.

Submit Review

const result = await client.reviews.submit({
  productId: 'product-id',
  rating: 5,
  title: 'Great product!',
  content: 'Highly recommended for everyone.',
  authorName: 'Jan',
  authorEmail: '[email protected]',
});

Reviews are moderated and appear after admin approval. One review per product per email, including concurrent requests. isVerifiedPurchase requires the authenticated customer to own a non-cancelled paid or delivered order for the exact product listing. Typing a buyer's email does not prove ownership. Legacy orders without a product ID qualify only when their inventory item maps to one listing in this shop.

Vote Helpful

const { data } = await client.reviews.voteHelpful('review-id', true);
// data.success === false when this visitor already voted on the review

An unsuccessful request must roll back an optimistic count and permit retry. A response with success: false must not add another vote.

Back in Stock

Subscribe an email to a notification for a sold-out product:

const { data, error } = await client.catalog.notifyWhenAvailable('product-id', '[email protected]');

On this page