Wishlist & Reviews
Wishlist management and product 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, submission? }The first page must be fetched on the server. Pass the returned data to
useProductReviews(productId, {page: 1, limit: 20, initialData, scope}) 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.
With purchaser-only moderation, submission describes the current caller:
{requiresVerifiedPurchase, canSubmit, reason}. Reasons are LOGIN_REQUIRED,
PURCHASE_REQUIRED, ALREADY_REVIEWED or null. Show a localized explanation and
sign-in link returning to the selected product when appropriate. The backend
always enforces the rule; hiding a form is not authorization. Older backends
may omit submission.
If customer tokens use HTTP-only cookies, fetch pages and submit reviews through
request-scoped server actions using the cookie-bound SDK client. A separate
browser SDK instance does not inherit those credentials. Scope hydrated query
keys by site, customer, product and page, and reset the form on identity changes.
For useProductReviews, pass scope: siteId + ":" + customerId (or a guest
marker); the hook keeps this scope in its query key.
A fresh failed server read must take precedence over older cached permission.
Keep the form unavailable until an explicit retry actually succeeds; a failed
retry with retained data is still a failure. Preserve a draft for the same
customer and product while recovering, and reset it when that identity changes.
Helpfulness voting can remain a direct browser request to preserve voter identity.
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. Purchaser-only shops
accept only authenticated buyers; only their verified reviews appear and count
toward ratings. One non-rejected review per product and customer is allowed,
including concurrent requests. Under the default policy, guest email duplicate
checks remain supported. 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 reviewAn 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]');