Authentication

Every request (except GET /openapi.json) sends the store’s API key and domain, plus the shopper’s identity.

Header	Required	Value
`X-Shopify-ApiKey`	Always	Your store’s API key
`X-Shopify-Shop`	Always	The store’s `myshopify.com` domain, e.g. `your-store.myshopify.com`
`X-Shopify-CustomerId`	Logged-in shopper	Numeric Shopify customer ID
`X-Shopify-SessionId`	Guest shopper	A guest ID your app creates and keeps
`Content-Type`	Requests with a body	`application/json`

GET /settings needs only the first two headers.

Get your API key

Open API Settings

In the Codebeans Wishlyst admin, go to Wishlist Settings → API Settings.

Generate a key

Click Generate new key and copy it. A new store has no key until you generate one.

Copy the connection details

The page also shows the shop domain and the base URL. Give all three to your developer.

Keep the key secret. Anyone who has it can read and change the wishlists of any shopper in your store. Use it from your own server, or from a mobile app you control. Never put it in public web code.If a key leaks, click Generate new key. The old key stops working at once. Reset restores the previous key, in case you generated a new one by mistake.

Identifying the shopper

Logged-in customer
Guest

Send the numeric customer ID, not the gid:// form:

X-Shopify-CustomerId: 7212345678901

The API checks on every call that the customer exists in the store. An unknown ID returns 401 CUSTOMER_REQUIRED.

The API trusts the customer ID you send, so your app must authenticate the shopper itself (for example with the Customer Account API) before calling it.

Create an ID the first time the app runs, store it on the device, and send it on every call:

X-Shopify-SessionId: sid_3f1c8a2e-6b0d-4c55-9f0e-2d7a1b9c4e11

If the store has guest wishlists switched off, every guest call returns 403 GUEST_DISABLED. Ask the shopper to log in.

When a guest logs in, send both headers once to POST /guest-wishlists/claim. The guest’s lists and shares move to the customer. The call is safe to repeat.

curl -X POST https://codebeans-wishlist.cblyst.com/api/v1/guest-wishlists/claim \
  -H "X-Shopify-ApiKey: $WISHLYST_API_KEY" \
  -H "X-Shopify-Shop: your-store.myshopify.com" \
  -H "X-Shopify-CustomerId: 7212345678901" \
  -H "X-Shopify-SessionId: sid_3f1c8a2e-6b0d-4c55-9f0e-2d7a1b9c4e11"

Then stop sending the session ID and use the customer ID only.

Authentication errors

Status	Code	Cause
401	`UNAUTHENTICATED`	Key or shop header missing or wrong, or the app is not installed on the store
401	`CUSTOMER_REQUIRED`	No shopper identity, unknown customer ID, or a guest call without a session ID
403	`API_ACCESS_NOT_IN_PLAN`	The store’s plan does not include API Access
403	`GUEST_DISABLED`	Guest call while guest wishlists are off

Getting started

Settings

Wishlists

Items

Product

Shared lists

Sharing

Account

Get your API key

Identifying the shopper

Authentication errors

​Get your API key

​Identifying the shopper

​Moving guest lists after login

​Authentication errors

Get your API key

Identifying the shopper

Moving guest lists after login

Authentication errors