Developer setup

Build on the current Wishlist Stack API.

Use the Shopify app proxy for Online Store themes. Use the direct API, Universal SDK, or Hydrogen integration for headless and custom storefronts.

Shopify Online Store: app proxy

Install Wishlist Stack and sign in as a storefront customer for private wishlist operations. Use the installed /apps/wishlist-stack proxy path; adjust it if the merchant has customized the path. Shopify signs the shopper identity. Native fetch calls do not require a merchant API key or a customer token in the theme.

const response = await fetch(
  '/apps/wishlist-stack/api/lists?page=1&pageSize=20',
  { credentials: 'same-origin' }
);
if (!response.ok) throw new Error('Wishlist request failed');
const { lists, pagination } = await response.json();

Use credentials: 'same-origin' and send Content-Type: application/json for mutations. Lists, items, membership, groups, duplication, and sharing use the same REST paths and payloads through the proxy. Retain the shopper’s selected list ID.

// Retain the list ID selected by the shopper.
const response = await fetch(
  '/apps/wishlist-stack/api/lists/' + encodeURIComponent(selectedListId) + '/share',
  {
    method: 'POST',
    credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json' },
  }
);
if (!response.ok) throw new Error('Unable to share this list');

Private endpoints require a logged-in customer. Public shared-list and shared-group reads can be accessed without login only when the owner has enabled sharing and the resource belongs to that merchant.

Universal JavaScript / TypeScript SDK

npm install @sdg.la/wishlist-stack-sdk

For direct connections, explicitly set the current API origin and provide the merchant key from Quick Start plus the customer’s Shopify access token for private operations.

import { createWishlistStackClient } from '@sdg.la/wishlist-stack-sdk';

const client = createWishlistStackClient({
  baseUrl: 'https://app.wishliststack.com',
  apiKey: 'YOUR_MERCHANT_API_KEY',
  customerAccessToken, // Resolve the signed-in Shopify customer at runtime.
});

const { lists } = await client.lists.getAll();

SDK 0.15.0 retains its constructor key and token requirements even when you point baseUrl at an app proxy. Native same-origin fetch is the simplest key-free proxy setup. For module-script examples and method signatures, see the Universal SDK reference. Use the explicit current origin above when adapting older examples.

Shopify Hydrogen

npm install @sdg.la/wishlist-stack-sdk @sdg.la/wishlist-stack-hydrogen

Set WISHLIST_STACK_BASE_URL=https://app.wishliststack.com and your merchant key in the server environment. The package supplies server-context helpers, React Router middleware, and React hooks. Follow the Hydrogen setup reference and the current Hydrogen instructions in the installed app.

If the browser calls the direct API, allow https://app.wishliststack.com in CSP connect-src and configure permitted storefront origins in the app. Resolve Shopify customer authentication for private operations at runtime.

Direct REST API

API origin: https://app.wishliststack.com. Direct calls use X-Wishlist-Stack-Api-Key; private customer-scoped endpoints also require X-Shopify-Customer-Access-Token.

const response = await fetch('https://app.wishliststack.com/api/lists?page=1&pageSize=20', {
  headers: {
    'X-Wishlist-Stack-Api-Key': merchantApiKey,
    'X-Shopify-Customer-Access-Token': customerAccessToken,
  },
});
if (!response.ok) throw new Error('Wishlist request failed');
const data = await response.json();

Pagination, batches, and feature access

• Request 20 records per page for storefront interfaces and follow the returned pagination metadata. Explicit page size is capped at 25.
• Use membership checks for up to 100 variant IDs rather than hydrating an entire list. Use the SDK’s batching and all-page helpers where appropriate.
• Create a list before adding items. Add responses include delta fields; complete legacy responses remain supported within safety budgets.
• New data is subject to safety limits: 1,000 lists and 1,000 groups per customer, 10,000 items per list, and 100,000 items per customer. Import validation has its separate 2,500-item-per-list limit.
• Group endpoints depend on merchant feature configuration. CSV imports and merchant analytics require Professional or Enterprise (or a separately managed entitlement).
• Handle authentication, capacity, and validation errors. Respect Retry-After on rate-limit or temporary-unavailability responses; do not blindly retry mutations.

App reference and merchant tools

In Shopify Admin, open Apps → Wishlist Stack → Quick Start and choose your integration method. The installed app also contains API Documentation, Universal SDK, Hydrogen SDK, product/metafield configuration, usage and plan controls, and eligible import and analytics tools.

Publish products to the Online Store so Shopify can supply current product details. The customer-account extension and custom storefront UI are separate integration surfaces; an app installation does not build a custom theme interface for you.

Install Wishlist Stack or contact [email protected] for help.