Authentication

API keys, store and shopper identity headers.

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

1. Open API Settings

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

2. Generate a key

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

3. 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

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.

Guest

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.

​

Moving guest lists after login

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