Examples & Full Flows

This section provides complete end-to-end flows and practical examples showing how to use the MiB Wishlist API in a real storefront.

Storage guidance (cookies / localStorage)

Use this as a simple baseline. Adjust for your security model and framework.

What to store

sessionId (guest): store on first visit and reuse in every request until login.
customerId (account): store after login and reuse for all authenticated requests.
Optional: wishlistShareCode if you want to re-open a shared wishlist.

Where to store

Cookie (recommended): first-party, same-site. Good for SSR and avoids losing identity on refresh.
localStorage: fine for SPA-only apps. Ensure it is read before the first API call.

When to store / update

After POST /profile/guest: persist sessionId.
After login (you know customerId): persist customerId.
After POST /profile/merge: keep customerId, and you can keep sessionId as a fallback or clear it.
After logout: clear customerId. Keep sessionId if you want to keep guest wishlist.

What NOT to store in the browser

API keys. Always call the API from your server or a secure backend proxy.

Example 1: Anonymous visitor saves an item

1) Create a guest profile

POST /profile/guest

{
  "sessionId": "anon-123",
  "email": null,
  "firstName": null,
  "lastName": null,
  "device": "mobile",
  "locale": "en"
}

Store sessionId in a cookie or localStorage for all next calls.

2) Track a product visit

POST /product/visit

{
  "identity": {
    "customerId": null,
    "sessionId": "anon-123",
    "device": "mobile",
    "firstName": null,
    "lastName": null,
    "locale": "en"
  },
  "productHandle": "sunglasses"
}

3) Add a product to wishlist

POST /item/add

{
  "identity": {
    "customerId": null,
    "sessionId": "anon-123",
    "email": null,
    "firstName": null,
    "lastName": null,
    "device": "mobile",
    "locale": "en"
  },
  "productId": "gid://shopify/Product/1",
  "variantId": "gid://shopify/ProductVariant/2",
  "productTitle": "Sunglasses",
  "variantTitle": "Black",
  "productHandle": "sunglasses",
  "image": "https://cdn.example.com/image.jpg",
  "price": "49.00",
  "compareAt": "69.00",
  "quantity": 1,
  "source": "pdp"
}

4) Render wishlist page

POST /item/list

{
  "identity": {
    "customerId": null,
    "sessionId": "anon-123",
    "device": "mobile",
    "firstName": null,
    "lastName": null,
    "locale": "en"
  }
}

Example 2: Guest logs in, merge and keep wishlist

1) Merge guest into customer

POST /profile/merge

{
  "customerId": "8769049329896",
  "sessionId": "anon-123",
  "email": "customer@example.com"
}

After login, store customerId and use it in identity. You can keep or clear the guest sessionId.

2) Fetch items for the account

POST /item/list

{
  "identity": {
    "customerId": "8769049329896",
    "sessionId": null,
    "device": "desktop",
    "firstName": null,
    "lastName": null,
    "locale": "en"
  }
}

POST /share

{
  "identity": {
    "customerId": "8769049329896",
    "sessionId": null,
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "device": "desktop",
    "locale": "en"
  },
  "channel": "Link"
}

2) Retrieve shared items

GET /share/:code/items

If you want to keep the last shared list, store shareCode from the response.

Example 4: Smart Save flow

This flow uses product visits to determine when to prompt Smart Save.

1) Track visit count

POST /product/visit

{
  "identity": {
    "customerId": null,
    "sessionId": "anon-123",
    "device": "mobile",
    "firstName": null,
    "lastName": null,
    "locale": "en"
  },
  "productHandle": "sunglasses"
}

2) Read visit count

GET /product/visit?sessionId=anon-123&productHandle=sunglasses

3) If count >= threshold, show Smart Save UI

Your frontend can decide whether to show a Smart Save prompt based on the visit count and config settings.

Example 5: Minimal server-side integration

Below is a minimal Node.js example showing how to call the API from a server:

const baseUrl = "wishlist-prod.mitbetter.com/api/wishlist/";
const apiKey = process.env.WISHLIST_API_KEY;

async function addToWishlist(payload) {
  const res = await fetch(`${baseUrl}/item/add`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error?.error ?? "Request failed");
  }

  return res.json();
}

Examples & Full Flows

On this page