Headless Overview

SimplerSuite Wishlist provides a dedicated Headless API and React SDK for headless storefronts. Works with Hydrogen, Next.js, Remix, Gatsby, and any React-based framework.

Requires Starter plan or above.

Architecture

Shopper's Browser
  → React SDK (@simplersuite/wishlist-react)
    → Headless API (HeadlessApi gateway)
      → DynamoDB (same data as embedded widget)

Customer Auth Flow:
  Shopper → Merchant Server (authenticates via Shopify Customer Account API)
    → POST /auth/token { api_key, api_secret, customer_id }
    ← { token: "ey...", expires_in: 3600 }
  Shopper uses JWT for all subsequent API calls

Two auth modes

Mode	Credential	Use case
Customer	JWT from POST /auth/token	Logged-in customer wishlists
Guest	Storefront Key + guest_id	Anonymous browsing, pre-login wishlists

Key concepts

• Same data: Headless and embedded widget share the same DynamoDB table. A customer’s wishlist is the same whether accessed via the widget or the SDK.
• Guest merge: When a guest logs in, the SDK automatically merges their local wishlist into their customer wishlist.
• No product data: The SDK manages wishlist membership (product IDs). Product details (title, image, price) come from your existing Shopify product queries.
• Optimistic updates: The React SDK updates UI immediately and rolls back on API failure.

Supported frameworks

• Shopify Hydrogen
• Next.js (App Router & Pages Router)
• Remix
• Gatsby
• Any React 18+ application