How does guest to login identity sync work?

When a shopper logs in, Wishlist Hero folds their anonymous wishlist into their account wishlist server side, and the storefront resyncs from the server. This reference documents the merge algorithm and the client sequence, so custom UIs stay correct across the login boundary.

The server merge

On the first wishlist call after login, the API reconciles the browser’s guest hash with the customer’s account:

1. Look up the wishlist by StoreCustomerId .
2. If the browser sent a different hash, fetch that guest wishlist.
3. Merge items by the key ProductId_variantId : union semantics, duplicates collapse and keep their original save details.
4. If the customer had no wishlist, the guest wishlist is adopted and rebound to the customer.
5. The customer’s email and name are back-filled from Shopify when missing.
6. The response flags merged: true  so clients know a reconciliation happened.

The merge is idempotent: repeating it with the same inputs changes nothing.

The client sequence

The storefront loader drives the resync:

1. On page load it reads the logged in customer ID from window.ShopifyAnalytics.meta.page.customerId .
2. It compares the customer’s server wishlist with the browser’s local guest reference.
3. On a difference it triggers the server merge, then clears stale local state and reloads items from the server.
4. Your listeners fire in order: wishlist-hero-customer-id , then wishlist-hero-wishlist-updated  with fresh server items (wishlist-hero-wishlist-items-from-server ).

document.addEventListener("wishlist-hero-wishlist-items-from-server", () => {
  renderList(window.WishListHero_SDK.GetWishListItems());
});

Listening to the server items event, rather than caching local items across login, is what keeps custom UIs honest: the guest snapshot is dead the moment a merge runs.

Custom build checklist

• Send the customer ID on identified calls: REST CreateOrGetExisting/:storeCustomerId  or the SDK’s customer context, so the merge can find the account list
• Re-render on merged  signals: any wishlist-hero-wishlist-updated  after login means re-fetch, not patch
• Do not persist the guest hash server side: it is a browser secret by design and is retired at merge
• Assume collapse of duplicates: two saves of one variant as guest and customer become one item

Edge cases

The merchant facing explanation lives in Guest lists and merge.