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 are project-scoped by URL.

Use the project segment in the endpoint and keep it stable for the whole request lifecycle. Thor resolves the segment at the gateway so storefront queries, cart mutations, customer flows, pricing, inventory, and checkout all execute against the same project.

Route requests through the project URL — do not attempt to override project context manually.

Storefront data is resolved in a commerce context, not just by project.

Product discovery and checkout depend on the store, currency, and customer-facing country or region. Pass the relevant context through the operation variables that the schema exposes, commonly storeId, priceCurrency, currency, and address country fields.

Thor’s starter storefront derives this context from the request, then passes it into Storefront API operations. Keep that pattern in your own integration: resolve context once at the edge or backend, then use the same values for product queries, cart creation, cart updates, shipping, and payment initialization.

Storefront media fields return delivery URLs that are ready to render.

Query Media.src from products, variants, or media connections, then add image transformation parameters to that URL in your storefront markup. The CDN accepts a small URL API for image output:

• width or w
• height or h
• format or f
• quality or q
• fit
• dpr

Use format=auto when you want the CDN to choose AVIF or WebP from the browser’s Accept header, with JPEG as the fallback. Use widths that match your layout and build srcset values from the same src instead of requesting one oversized original for every viewport.

For the full URL contract and storefront examples, see Image optimization.

Storefront requests do not use Admin API keys.

Public catalog and cart flows are scoped by the project URL and request context. Customer-specific flows can add an Authorization: Bearer ... customer session token so Thor can resolve customer data, customer groups, and customer-specific pricing.

Keep Admin API keys server-side and use them only with the Admin API.

Storefront IDs use the same Thor typed ID format as the Admin API.

Treat IDs and cursors as opaque strings in your storefront. Store cart IDs in a secure cookie or server session, pass product and variant IDs back to mutations exactly as returned, and use cursor pagination for product, category, collection, address, order, and payment lists.

For generic refetches, use node(id: ID!) and inline fragments for the resource shape your UI expects.

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.