Shopper Engagement: Wishlist, Reviews & Messaging

One signed-in shopper moves through the three surfaces that surround a purchase: they save the Watch to their wishlist and later move it into the cart, they review the product they bought, and they open a support thread about the order. Along the way come the atomic wishlist-to-cart move, a second review meeting a 409, a deleted message, and the two realtime connection shapes. Every call here acts on a signed-in shopper’s own data, so it pairs an API key with the shopper’s session token in xAuthToken. Workflow Examples has the client setup, and Storefront Checkout covers minting that session token. One shopper — Jane Doe, customer 9489529e-69b0-4e84-bea7-62c499085bd9 — and one product, the Samsung Galaxy Watch 6 (0186665f-…, variant e98631a9-…), carry throughout.

Wishlist, review, and messaging writes are browser-origin storefront writes, so the publishable client covers them; the shopper’s xAuthToken is what proves ownership. Moderating reviews and replying from the store side happen in the merchant admin and are not API actions.

Wishlist

The shopper is not ready to buy, and saves the Watch for later. Wishlists are always customer-scoped, so every call carries customer_id and the matching xAuthToken.

1. Adding to the wishlist

addToWishlist saves a variant and returns the refreshed wishlist (201 Created). Its items carry product_price, the price quoted at the time of saving — a field the cart’s items do not have.

const wishlist = await storefront.cartWishlist.addToWishlist({
  xAuthToken: session.access_token,
  requestBody: {
    variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a',
    customer_id: '9489529e-69b0-4e84-bea7-62c499085bd9',
  },
});

Response

{
  "items": [
    {
      "id": "2dac3a23-afec-4b6a-a369-e7bdb1f3bc32",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "product_price": 299,
      "thumbnail_url": "https://cdn.tybritelabs.com/.../samsung-galaxy-watch-6.jpg"
    }
  ]
}

A variant can be saved once per customer. Adding the same variant again returns 409 Conflict ({ "error": { "code": "conflict", "message": "Item already exists in wishlist" } }) rather than creating a duplicate, which makes the 409 itself a reliable “already saved” signal.

2. Reading the wishlist

getWishlist lists the customer’s saved items in the same item shape as the add response. customer_id is required, as anonymous wishlists are not supported.

const { items } = await storefront.cartWishlist.getWishlist({
  xAuthToken: session.access_token,
  customerId: '9489529e-69b0-4e84-bea7-62c499085bd9',
});
// → items[0].product_name === 'Samsung Galaxy Watch 6', items[0].product_price === 299

Response

{
  "items": [
    {
      "id": "2dac3a23-afec-4b6a-a369-e7bdb1f3bc32",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "product_price": 299,
      "thumbnail_url": "https://cdn.tybritelabs.com/.../samsung-galaxy-watch-6.jpg"
    }
  ]
}

3. Moving a saved item to the cart (atomic)

The shopper decides to buy. moveWishlistToCart is one atomic step: it validates stock, adds the item to the cart or merges it with an existing line, removes it from the wishlist, and returns the refreshed cart. The response echoes removed_wishlist_item_id to identify the saved item that is gone, and the returned cart item carries a new id, being a cart row rather than the wishlist row.

const cart = await storefront.cartWishlist.moveWishlistToCart({
  xAuthToken: session.access_token,
  requestBody: {
    wishlist_item_id: '2dac3a23-afec-4b6a-a369-e7bdb1f3bc32',
    customer_id: '9489529e-69b0-4e84-bea7-62c499085bd9',
    quantity: 1,
  },
});

Response

{
  "success": true,
  "message": "Item moved from wishlist to cart",
  "removed_wishlist_item_id": "2dac3a23-afec-4b6a-a369-e7bdb1f3bc32",
  "items": [
    {
      "id": "845e8724-a3dc-432c-9771-26a4173ec48c",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "quantity": 1
    }
  ]
}

4. Removing a saved item

A shopper discarding a saved item instead reaches removeFromWishlist, which deletes it by id. The customer_id query param is required, which is what scopes the delete to its owner.

const removed = await storefront.cartWishlist.removeFromWishlist({
  xAuthToken: session.access_token,
  id: '2dac3a23-afec-4b6a-a369-e7bdb1f3bc32',
  customerId: '9489529e-69b0-4e84-bea7-62c499085bd9',
});
// → { success: true, message: 'Item removed from wishlist' }

Response

{ "success": true, "message": "Item removed from wishlist" }

The wishlist sits alongside the cart in the same cartWishlist service. From here the Watch goes into the storefront checkout and is paid for, and the shopper returns to review it.

Reviews

The Watch has arrived and the shopper wants to review it. Reviews start hidden and become public only once the merchant approves them.

5. Submitting a review (starts `pending`)

submitReview creates the review with status: "pending", and it appears in public listings only after the merchant approves it in their admin. An order_id belonging to the shopper flags the review verified_purchase: true.

const { review } = await storefront.reviews.submitReview({
  xAuthToken: session.access_token,
  requestBody: {
    product_id: '0186665f-f0a1-4c79-976a-919b5b1c2daa',
    rating: 5,
    title: 'Outstanding quality',
    body: 'Exactly as described — fast shipping and great build quality. Would buy again.',
  },
});

Response

{
  "review": {
    "id": "11bc03d9-d1cb-4833-b9d2-f0b016104cde",
    "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
    "variant_id": null,
    "order_id": null,
    "customer_id": "73ec7ad0-d9aa-4ee2-a382-efa690eaab01",
    "customer_name": "Jane Doe",
    "rating": 5,
    "title": "Outstanding quality",
    "body": "Exactly as described — fast shipping and great build quality. Would buy again.",
    "media_urls": [],
    "status": "pending",
    "rejection_reason": null,
    "helpful_count": 0,
    "verified_purchase": false,
    "created_at": "2026-06-20T10:44:28.706637+00:00",
    "updated_at": "2026-06-20T10:44:28.706637+00:00"
  }
}

6. The duplicate review → `409 Conflict`

A shopper holds only one non-rejected review per product, so a second review from Jane for the same Watch returns 409. The resolution is editing the existing review rather than retrying the submit.

try {
  await storefront.reviews.submitReview({
    xAuthToken: session.access_token,
    requestBody: {
      product_id: '0186665f-f0a1-4c79-976a-919b5b1c2daa',
      rating: 4,
      title: 'Changed my mind a little',
      body: 'Still good, but the battery drains faster than I expected.',
    },
  });
} catch (err) {
  // err.status === 409 — the shopper already reviewed this product
}

Response (409)

{
  "error": {
    "code": "conflict",
    "message": "You have already reviewed this product"
  }
}

7. Listing approved reviews (public, with summary)

Once the merchant approves the first review, listReviews backs the product page’s review section. On a publishable key it returns only approved reviews and always includes a summary block — average rating plus star distribution. This is public catalog data, so no customer token is involved.

const { reviews, summary } = await storefront.reviews.listReviews({
  productId: '0186665f-f0a1-4c79-976a-919b5b1c2daa',
});
// → summary.average_rating === 5, summary.five_star === 1

Response

{
  "reviews": [
    {
      "id": "11bc03d9-d1cb-4833-b9d2-f0b016104cde",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": null,
      "order_id": null,
      "customer_id": "73ec7ad0-d9aa-4ee2-a382-efa690eaab01",
      "customer_name": "Jane Doe",
      "rating": 5,
      "title": "Outstanding quality",
      "body": "Exactly as described — fast shipping and great build quality. Would buy again.",
      "media_urls": [],
      "status": "approved",
      "rejection_reason": null,
      "helpful_count": 0,
      "verified_purchase": false,
      "created_at": "2026-06-20T10:44:28.706637+00:00",
      "updated_at": "2026-06-20T10:44:28.706637+00:00"
    }
  ],
  "pagination": { "limit": 20, "has_more": false, "next_cursor": null },
  "summary": {
    "total_reviews": 1,
    "average_rating": 5,
    "five_star": 1,
    "four_star": 0,
    "three_star": 0,
    "two_star": 0,
    "one_star": 0,
    "verified_count": 0
  }
}

rating and sort (newest / oldest / highest / lowest) filter and order the list, and the cursor from pagination.next_cursor pages it. storefront.reviews.getReview({ id }) fetches one review by id.

8. Marking a review helpful

Upvotes let a product page surface the reviews shoppers found useful. Only approved reviews accept votes, and there is no built-in de-duplication, so per-shopper voting state belongs in your own UI.

const { helpful_count } = await storefront.reviews.markReviewHelpful({
  id: '11bc03d9-d1cb-4833-b9d2-f0b016104cde',
});
// → helpful_count === 1

Response

{ "helpful_count": 1 }

A shopper can remove their own review with storefront.reviews.deleteReview({ id, xAuthToken: session.access_token }) — it returns { "success": true, "message": "Review deleted" }. Deleting someone else’s review returns 403.

Messaging

The shopper opens a support thread about the order, and it stays live so the store’s replies arrive without polling.

9. Starting a conversation

createConversation opens a thread and posts the shopper’s first message in one call. thread_type classifies the inquiry (general, order_inquiry, product_inquiry, support, complaint, delivery, return, refund, technical). A customer_id comes with the matching xAuthToken.

const { thread } = await storefront.messaging.createConversation({
  xAuthToken: session.access_token,
  requestBody: {
    customer_id: '88ad3683-d291-4c70-8f8b-9903a42bde1b',
    customer_name: 'Jane Doe',
    customer_email: 'jane.doe@example.com',
    subject: 'Question about my order',
    message: 'Hi — I placed an order and wanted to check the expected delivery window.',
    thread_type: 'order_inquiry',
  },
});
// → thread.id is the conversation you send follow-ups to

Response

{
  "thread": {
    "id": "06084af6-7334-43d6-82c0-935f92335a25",
    "subject": "Question about my order",
    "status": "active",
    "priority": "normal"
  },
  "message": {
    "id": "c423c11e-ab5f-40ab-8e17-429a39710d60",
    "created_at": "2026-06-20T11:28:58.245993+00:00"
  }
}

10. Sending a follow-up message

sendMessage appends to the thread just opened, with the text in message. The token must own the thread; otherwise the call returns 403.

const { message } = await storefront.messaging.sendMessage({
  xAuthToken: session.access_token,
  id: '06084af6-7334-43d6-82c0-935f92335a25',
  requestBody: { message: 'Thanks! Also, can I add gift wrapping to this order?' },
});

Response

{
  "message": {
    "id": "33e2c744-37a9-42df-a9df-447715526a41",
    "created_at": "2026-06-20T11:29:02.467216+00:00"
  }
}

11. Listing threads and reading the conversation

listThreads backs the shopper’s inbox, filtered by customer_id, with pinned threads first; getThreadMessages loads one conversation’s messages, oldest-first by default.

const { threads } = await storefront.messaging.listThreads({
  xAuthToken: session.access_token,
  customerId: '88ad3683-d291-4c70-8f8b-9903a42bde1b',
});

Response

{
  "threads": [
    {
      "id": "06084af6-7334-43d6-82c0-935f92335a25",
      "subject": "Question about my order",
      "status": "active",
      "priority": "normal",
      "thread_type": "order_inquiry",
      "last_message_at": "2026-06-20T11:28:58.338+00:00",
      "last_message_by": "customer",
      "unread_count_customer": 0,
      "unread_count_store": 1,
      "is_archived": false,
      "is_muted": false,
      "is_pinned": false
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

const { messages } = await storefront.messaging.getThreadMessages({
  xAuthToken: session.access_token,
  id: '06084af6-7334-43d6-82c0-935f92335a25',
});
// → the two messages we sent, oldest-first, with is_edited/is_deleted flags

Response

{
  "messages": [
    {
      "id": "c423c11e-ab5f-40ab-8e17-429a39710d60",
      "message_content": "Hi — I placed an order and wanted to check the expected delivery window.",
      "message_type": "text",
      "sender_type": "customer",
      "sender_id": "88ad3683-d291-4c70-8f8b-9903a42bde1b",
      "sender_name": "Jane Doe",
      "attachments": [],
      "metadata": {},
      "message_status": "sent",
      "read_at": null,
      "is_edited": false,
      "is_deleted": false,
      "created_at": "2026-06-20T11:28:58.245993+00:00",
      "updated_at": "2026-06-20T11:28:58.245993+00:00"
    },
    {
      "id": "33e2c744-37a9-42df-a9df-447715526a41",
      "message_content": "Thanks! Also, can I add gift wrapping to this order?",
      "message_type": "text",
      "sender_type": "customer",
      "sender_id": "88ad3683-d291-4c70-8f8b-9903a42bde1b",
      "sender_name": "Jane Doe",
      "attachments": [],
      "metadata": {},
      "message_status": "sent",
      "read_at": null,
      "is_edited": false,
      "is_deleted": false,
      "created_at": "2026-06-20T11:29:02.467216+00:00",
      "updated_at": "2026-06-20T11:29:02.467216+00:00"
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

12. Editing or deleting a message

A shopper can revise or retract a message they sent. Both calls require a secret key and so run server-side. editMessage rewrites the content and stamps is_edited: true plus edited_at; deleteMessage soft-deletes — the row stays, marked is_deleted and excluded from the default message list — and returns the deleted_at timestamp.

const edited = await server.messaging.editMessage({
  xAuthToken: session.access_token,
  id: 'c423c11e-ab5f-40ab-8e17-429a39710d60',
  requestBody: { message_content: 'Hi — checking the delivery window (order ORD-1781955473455).' },
});

Response

{
  "message": {
    "id": "c423c11e-ab5f-40ab-8e17-429a39710d60",
    "message_content": "Hi — checking the delivery window (order ORD-1781955473455).",
    "is_edited": true,
    "edited_at": "2026-06-20T13:52:41.118+00:00",
    "updated_at": "2026-06-20T13:52:41.118+00:00"
  }
}

const deleted = await server.messaging.deleteMessage({
  xAuthToken: session.access_token,
  id: 'c423c11e-ab5f-40ab-8e17-429a39710d60',
});
// → { success: true, message_id: '...', deleted_at: '...' } — soft delete, row is hidden not gone

Response

{
  "success": true,
  "message_id": "c423c11e-ab5f-40ab-8e17-429a39710d60",
  "deleted_at": "2026-06-20T13:53:02.704+00:00"
}

13. Marking the thread read

Opening the conversation clears the shopper’s unread state.

const result = await storefront.messaging.markThreadRead({
  xAuthToken: session.access_token,
  id: '06084af6-7334-43d6-82c0-935f92335a25',
});

Response

{
  "success": true,
  "thread_id": "06084af6-7334-43d6-82c0-935f92335a25"
}

14. Streaming replies in real time

The subscribeToThread helper opens a WebSocket to the thread, delivering the store’s replies as they are sent rather than on a polling interval. The same call covers a shopper who signed in through Galactic Core and one who signed in through your own identity provider, and it pulls in no extra packages: it uses the platform WebSocket, available in browsers, Deno, Bun, and Node 22+.

import { subscribeToThread } from '@tybrite-labs/sdk';

// A shopper signed in through Galactic Core — pass their session token:
const unsubscribe = subscribeToThread({
  apiKey: 'tybrite_pk_live_...',
  threadId: '06084af6-7334-43d6-82c0-935f92335a25',
  authToken: session.access_token,
  onMessage: (msg) => {
    console.log('New message:', msg.message_content);
  },
});

// later, when the shopper closes the thread:
unsubscribe();

For a shopper authenticated with your own identity provider, the signed assertion goes in externalAuth in place of authToken; everything else is identical:

const unsubscribe = subscribeToThread({
  apiKey: 'tybrite_pk_live_...',
  threadId: '06084af6-7334-43d6-82c0-935f92335a25',
  externalAuth: signedAssertion, // your IdP's HMAC-signed identity assertion
  onMessage: (msg) => console.log('New message:', msg.message_content),
});

The connection is authorized server-side: the credential is validated and confirmed to be the thread’s participant before the socket is accepted, so a shopper only ever receives their own thread’s messages.

A connection managed directly, without the helper, is a WebSocket to GET /v1/messaging/threads/{id}/subscribe carrying ?api_key= and either ?auth_token= or ?external_auth= in the URL, since browsers cannot set request headers on a WebSocket. The server pushes one JSON frame per new message: { "type": "message.created", "payload": { "thread_id", "message" } }. The text frame ping keeps an idle connection alive, and the server replies pong.Customer authentication covers bringing your own identity provider.

What’s next

The shopper arrived from a storefront checkout, which the wishlist, reviews, and support thread sit around.
A returning shopper can track orders and lodge a return, often opening a return-type thread from the same inbox.
Search & Discovery captures the add_to_wishlist event that put the Watch on the wishlist to begin with.
Wishlist, reviews, and messaging carry over to a multi-merchant storefront — see the Marketplace split checkout and unified shopper profile.

Overview

Storefront

Marketplace

Integrations

Reference

Wishlist

1. Adding to the wishlist

2. Reading the wishlist

3. Moving a saved item to the cart (atomic)

4. Removing a saved item

Reviews

5. Submitting a review (starts `pending`)

6. The duplicate review → `409 Conflict`

7. Listing approved reviews (public, with summary)

8. Marking a review helpful

Messaging

9. Starting a conversation

10. Sending a follow-up message

11. Listing threads and reading the conversation

12. Editing or deleting a message

13. Marking the thread read

14. Streaming replies in real time

What’s next

​Wishlist

​1. Adding to the wishlist

​2. Reading the wishlist

​3. Moving a saved item to the cart (atomic)

​4. Removing a saved item

​Reviews

​5. Submitting a review (starts pending)

​6. The duplicate review → 409 Conflict

​7. Listing approved reviews (public, with summary)

​8. Marking a review helpful

​Messaging

​9. Starting a conversation

​10. Sending a follow-up message

​11. Listing threads and reading the conversation

​12. Editing or deleting a message

​13. Marking the thread read

​14. Streaming replies in real time

​What’s next

Wishlist

1. Adding to the wishlist

2. Reading the wishlist

3. Moving a saved item to the cart (atomic)

4. Removing a saved item

Reviews

5. Submitting a review (starts `pending`)

6. The duplicate review → `409 Conflict`

7. Listing approved reviews (public, with summary)

8. Marking a review helpful

Messaging

9. Starting a conversation

10. Sending a follow-up message

11. Listing threads and reading the conversation

12. Editing or deleting a message

13. Marking the thread read

14. Streaming replies in real time

What’s next