Introduction

The Shopper API is a versioned REST API that gives your own app everything the storefront wishlist does. Shoppers can create lists, save and move products, share lists and open lists shared with them, using the same data as your Shopify storefront.

Requires a plan that includes API Access.

Base URL

https://codebeans-wishlist.cblyst.com/api/v1

You can also find the base URL in the app under Wishlist Settings → API Settings → Connection details.

Quick example

curl https://codebeans-wishlist.cblyst.com/api/v1/wishlists \
  -H "X-Shopify-ApiKey: $WISHLYST_API_KEY" \
  -H "X-Shopify-Shop: your-store.myshopify.com" \
  -H "X-Shopify-CustomerId: 7212345678901"

{
  "data": [
    {
      "id": 52,
      "name": "Birthday picks",
      "isPublic": true,
      "createdAt": "2026-09-28T10:00:00.000Z",
      "items": [ { "id": 74, "productId": "8060316581941", "variantId": "44986123976757", "title": "Classic Leather Bag", "price": "2499.0", "currency": "INR", "availableForSale": true } ],
      "sharedWith": [],
      "sharedBy": null
    }
  ],
  "pagination": { "page": 1, "limit": 5, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPrevPage": false }
}

Recommended app flow

Load settings at startup

Call GET /settings once, and again when the shopper changes language. It returns the merchant’s text, wishlist mode (single or multiple lists), page sizes and plan features. Use them to match your UI to the store.

Identify the shopper

Send X-Shopify-CustomerId for a logged-in customer, or X-Shopify-SessionId for a guest. See Authentication.

Show the heart state on product pages

GET /products/{productId}/wishlists tells you which lists contain the product.

Save from the picker

PUT /products/{productId}/wishlists sends the final state of the picker in one call: lists ticked, lists unticked and new lists.

Merge guest lists at login

When a guest logs in, call POST /guest-wishlists/claim with both IDs.

Conventions


Format	JSON request and response bodies. Errors use `application/problem+json`.
Success body	`{ "data": …, "pagination"?: …, "meta"?: … }`. Writes also return `message`, `messageKey` and sometimes `messageParams`.
IDs	Wishlist, item, product and variant IDs are numeric strings or numbers.
Prices	Decimal strings, priced for the `country` and `locale` query parameters (defaults `US` and `EN`).
Versioning	Every response has an `API-Version` header. Additions stay in v1. Breaking changes ship as `/api/v2`.
CORS	All origins are allowed, so the API can be called from a browser. Keep your API key out of public web code.

Showing messages to shoppers

Write responses and errors include a messageKey. Look it up in widgetSettings from GET /settings to show the merchant’s own, translated text, and replace {placeholders} with values from messageParams. Fall back to message when the key is missing.

function shopperMessage(body, widgetSettings) {
  let text = (body.messageKey && widgetSettings[body.messageKey]) || body.message || '';
  for (const [k, v] of Object.entries(body.messageParams || {})) {
    text = text.replaceAll(`{${k}}`, v);
  }
  return text;
}

Machine-readable spec

The OpenAPI document is public at GET /api/v1/openapi.json. Use it to generate a client.

Getting started

Settings

Wishlists

Items

Product

Shared lists

Sharing

Account

Base URL

Quick example

Recommended app flow

Conventions

Showing messages to shoppers

Machine-readable spec

​Base URL

​Quick example

​Recommended app flow

​Conventions

​Showing messages to shoppers

​Machine-readable spec

Base URL

Quick example

Recommended app flow

Conventions

Showing messages to shoppers

Machine-readable spec