Guest Support

How guest mode works

When no customerToken is provided to the WishlistProvider, the SDK operates in guest mode:

1. A unique guest ID (g_<random>) is generated and stored in localStorage
2. The X-Storefront-Key header identifies the shop
3. The guest_id query parameter identifies the guest
4. Wishlist items are persisted both server-side (DynamoDB) and in localStorage (for instant renders)

Automatic merge on login

When customerToken transitions from undefined to a valid JWT:

1. The SDK reads the guest’s cached items from localStorage
2. Calls POST /wishlist/merge to merge them into the customer’s server-side wishlist
3. Clears guest localStorage data
4. Fetches the merged wishlist from the server

This happens automatically — no code needed.

// The merge triggers automatically when customerToken changes
<WishlistProvider
  apiBase={apiBase}
  storefrontKey="sfk_..."
  customerToken={isLoggedIn ? jwt : undefined}
>

Guest access settings

Merchants can restrict wishlists to logged-in customers only via the Settings page. When guestAccess is set to "logged_in_only", guest API calls return a 403 error.

localStorage keys

Key	Content
simplersuite_guest_id	Guest ID (g_<12 chars>)
simplersuite_guest_wishlist	Cached items JSON array

SSR safety

All localStorage access is gated behind typeof window !== "undefined". The SDK is safe to use in server-rendered frameworks.

Manual guest storage access

import {
  getOrCreateGuestId,
  clearGuestId,
  getGuestWishlist,
  setGuestWishlist,
  clearGuestWishlist,
} from "@simplersuite/wishlist-react";