Every request must identify the shop and carry exactly one credential. Requests that send more than one credential header are rejected with 401.

There are two ways to authenticate, depending on who is calling.

1. API key — server-to-server

For your own backend / integrations acting on behalf of a store.

Header	Required	Value
X-Shop-Domain	yes	The store's *.myshopify.com domain
X-Api-Key	yes	A key created in the Froonze admin (Shop settings → API keys), format frcp_…
X-Customer-Id	optional	A Shopify customer id to act on behalf of a specific customer

API keys are shop-scoped and bound to the X-Shop-Domain they were issued for. They are shown once at creation — store them securely and revoke them at any time. The store owner must first enable the public API and create a key. Customer-scoped fields return null unless the API is enabled. Include X-Customer-Id to read a specific customer's data; omit it for shop-only queries.

curl https://api.froonze.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'X-Shop-Domain: your-store.myshopify.com' \
  -H 'X-Api-Key: frcp_xxx' \
  -H 'X-Customer-Id: 1234567890' \
  -d '{"query":"{ shop { customer { loyaltyData { points } } } }"}'

2. Customer account token — customer JWT

For customer-facing surfaces (Shopify Customer Account UI extensions, mobile apps) where the signed-in customer calls on their own behalf.

Header	Required	Value
X-Shop-Domain	yes	The store's *.myshopify.com domain
X-Customer-Account-Token	yes	A Shopify Customer Account API id_token

The id_token comes from Shopify's Customer Account API OAuth flow — see Authenticate customers with the Customer Account API and the Customer Account API reference. Send the id_token, not the access_token — the latter may be opaque and cannot be verified.

The token's signature is verified against the shop's JWKS and is bound to the store via the token's iss claim; the customer in context is the token's sub. Do not send X-Customer-Id with this flow — the identity comes from the token, and requests that include it are rejected.

curl https://api.froonze.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'X-Shop-Domain: your-store.myshopify.com' \
  -H 'X-Customer-Account-Token: eyJhbGciOi…' \
  -d '{"query":"{ shop { customer { loyaltyData { points } } } }"}'

Errors

Status	Meaning
401 Unauthorized	Missing/invalid credential, more than one credential header, unknown shop, or (JWT flow) X-Customer-Id was sent
403 Forbidden	The store has not enabled the public API, or this IP is temporarily blocked after repeated failed authentications
429 Too Many Requests	Rate limit exceeded — retry after the seconds given in Retry-After

The API deliberately does not expose a customer's wishlist as a query field. A storefront reads the wishlist on every page load, which would spend the whole per-token rate-limit budget on data Shopify already serves you for free.

Read it from the customer metafield instead, with the Storefront API or the Customer Account API on the frontend:

customer.metafields.froonze_cp.wishlist

Namespace	froonze_cp
Key	wishlist
Type	json
Access	Storefront PUBLIC_READ, customer account READ_WRITE

Froonze keeps this metafield up to date: every change to a wishlist — through the mutations in this API or anywhere else — republishes the payload. So read the metafield for display, and use the wishlist mutations here to change it. There is no rate limit on reading a metafield, and no round trip through Froonze.

The public API is enabled per store, and each plugin unlocks only its own part of the schema — a store reaches the loyalty fields on the top Loyalty plan and the wishlist fields on the top Wishlist plan. Qualifying through one plugin does not expose the other.

Fields you are not entitled to resolve as null (or an empty page, for referrals and loyaltyEvents) rather than erroring, and shop itself is null when the store's plan includes no API access at all. Mutations return an error message instead.

Limits are per credential, not per IP, so one integration cannot exhaust another's budget.

Each credential gets a leaky bucket: a burst allowance that refills continuously at a steady rate, rather than a counter that resets on the clock.

Flow	Burst	Sustained rate
API key (X-Api-Key)	50 requests	2/second
Customer token (X-Customer-Account-Token)	10 requests	1/second

You may spend the whole burst at once — after that, capacity comes back gradually, so a steady pace at or below the sustained rate never hits the limit. Idle time does not bank extra credit: the bucket never fills past its burst size.

Exceeding a limit returns 429 with a Retry-After header giving the whole seconds until enough capacity has drained for one more request. Back off for that long; retrying sooner just costs you another rejection.

Repeated failed authentications are handled separately: 10 failures from one IP within 10 minutes blocks that IP for 15 minutes with a 403. Cache your credentials rather than re-authenticating per request, and stop retrying a rejected credential.

Every document is checked before it executes:

Limit	Value
Maximum query depth	10
Maximum query complexity	500
Maximum query length	5000 tokens
Validation timeout	2 seconds

Most fields cost 1 point of complexity. Fields that do real work per resolution cost 10: loyaltyDigitalCardUrls, and referrals / loyaltyEvents when asked for a page other than the first (page 1 is served from cache). Requesting the same expensive field many times over under different aliases is what these budgets exist to stop.

Paginated fields accept page 1 to 10 (10 items per page). Anything outside that range is an error rather than an empty page.

Query-limit breaches return 200 with the GraphQL errors array populated, as validation errors rather than HTTP errors.