Storefront API

The Storefront API is the runtime API for product discovery, carts, checkout, and customer-facing account flows.

It resolves the configuration created in the Admin API against live request context such as:

• store
• currency
• country
• price channel
• customer identity or customer groups

Treat it as the read and transaction surface your storefront uses at request time. The data it returns is already filtered by the store and channel rules active for that request.

Storefront requests also use X-Api-Key as the base transport credential.

Customer-facing flows may add customer access tokens on top, but the API key is still the base application credential. In practice, most teams call the Storefront API from their backend, edge layer, or BFF and avoid exposing operational credentials directly to the browser.

Storefront rate limiting is also cost-based.

Query responses can include extensions.cost, which tells you how much budget the request consumed and how much remains. That is the signal to use for client backoff, cache strategy, and cart mutation pacing.

Practical guidance:

• cache product and collection queries aggressively
• debounce cart updates from the UI
• avoid replaying the same high-cost query multiple times in a single page load

Storefront failures also follow GraphQL conventions.

You can receive:

• top-level errors for execution failures
• partial data when only part of the selection failed
• typed domain errors in payloads for cart, customer, or checkout operations

Always treat the response body, not just the HTTP status, as the source of truth. A request can return 200 OK and still contain application-level failures that your client needs to handle explicitly.

For Thor-specific behavior like query syntax, see Concepts.