> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-wishlyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Build Codebeans Wishlyst wishlists into a mobile app or a headless storefront.

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.

> [!NOTE]
>
> 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

```bash theme={null}
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"
```

```json theme={null}
{
  "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

**1. Load settings at startup**

Call [`GET /settings`](https://codebeans-wishlyst.mintlify.site/api-reference/endpoints/settings/get) 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.

**2. Identify the shopper**

Send `X-Shopify-CustomerId` for a logged-in customer, or `X-Shopify-SessionId` for a guest. See [Authentication](https://codebeans-wishlyst.mintlify.site/api-reference/authentication.md).

**3. Show the heart state on product pages**

[`GET /products/{productId}/wishlists`](https://codebeans-wishlyst.mintlify.site/api-reference/endpoints/product/get-wishlists) tells you which lists contain the product.

**4. Save from the picker**

[`PUT /products/{productId}/wishlists`](https://codebeans-wishlyst.mintlify.site/api-reference/endpoints/product/set-wishlists) sends the final state of the picker in one call: lists ticked, lists unticked and new lists.

**5. Merge guest lists at login**

When a guest logs in, call [`POST /guest-wishlists/claim`](https://codebeans-wishlyst.mintlify.site/api-reference/endpoints/account/claim-guest) 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.

```js theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.