Storefront API

Authentication

Storefront authentication is separate from Admin API authentication. Never expose an Admin API key in storefront code.

A project can allow anonymous Storefront API access or require a storefront token. For a protected storefront, send the token in x-thor-storefront-token. This controls access to the project’s storefront schema. It does not identify a customer.

Customer account operations use a customer access token returned by customerAccessTokenCreate. Send it as Authorization: Bearer <token> when querying the signed-in customer or performing customer-specific operations.

Keep both credentials server-side when possible. See Customer authentication for sign-in, refresh, registration, and session storage guidance.

Commerce context

Storefront data is resolved for a particular market and shopper, not only for a project.

Pass the store, price channel, currency, country, and locale accepted by each operation. Thor uses that context to select visible products, applicable prices, inventory, discounts, shipping methods, and payment gateways.

Resolve the context once in your application and keep it consistent through discovery and checkout. Create the cart with the same store, channel, currency, and country used for product queries, then treat the returned cart prices and totals as authoritative.

Learn how to model the context in Storefront request context.

Catalog and discovery

Query products individually by ID or slug, or build browsable collections with products, categories, and collections.

Product results include variants, selected attributes, contextual price and availability, media, categories, collections, tags, and public metafields. Product lists support cursor pagination, sorting, facets, and a search query so filtering stays on the API rather than in the browser.

Money is returned in integer minor units with its currency code and fraction digits. Render product media from the returned delivery URL and use Thor’s image transformations to request the size and format your layout needs.

Explore the products query, then use the shared Search query language and Facets guides to build filters. Read Image optimization for responsive product media.

Cart and checkout

Create a cart with the shopper’s commerce context and optional initial line items. The returned cart is the source of truth for line prices, discounts, tax, shipping choices, payment eligibility, and totals.

Use cart mutations to add or update items, apply discount codes, set addresses and shipping lines, initialize a payment session, and complete checkout. Re-read the returned cart after every mutation because one change can affect several parts of checkout.

For the shortest integration, redirect the shopper to checkoutUrl. For a custom checkout, follow the ordered flow in Cart and checkout.

Customer accounts

Build registration, activation, sign-in, password recovery, addresses, and account profile flows with the same Storefront API.

Signing in returns a short-lived access token, a refresh token, and the access-token lifetime. Use the access token to query customer. Refresh it as part of your application session and store both tokens as secrets.

Customer context can also affect prices, discounts, shipping, and payment eligibility. After sign-in or sign-out, re-query customer-sensitive product and cart data rather than continuing with a stale anonymous result.

Start with customerAccessTokenCreate and the Customer authentication guide.

GraphQL basics

The Admin and Storefront APIs use the same GraphQL fundamentals. Name every operation, declare external values as variables, and select only the fields the caller needs. Queries read data. Mutations change data and commonly accept one typed input object.

Field names, arguments, and nullability are defined independently by each schema. Use the generated API reference as the source of truth, and keep project routing and credentials separate from the GraphQL document.

Fragments reuse selections without making another request. Use inline fragments and __typename when a field returns an interface or union.

Pagination

List fields generally return cursor connections. Use nodes when you only need records, or edges { cursor node } when each item's cursor is useful. Request pageInfo with the page.

For forward pagination, request first items and pass the returned endCursor to after. For backward pagination, use last, before, andstartCursor. A page can contain at most 100 items. Do not pass a first or last value greater than 100.

Treat cursors as opaque. Keep filters, sorting, and Storefront commerce context unchanged while traversing a connection, and restart from the first page after any of those inputs changes.

Typed IDs

Thor IDs are opaque strings with a resource prefix, such as product_..., vid_..., cart_..., or order_.... The prefix lets Thor reject an ID passed to the wrong argument early.

Store and pass the complete value unchanged. Do not generate IDs, decode their payloads, replace prefixes, or infer properties from them. Cursors are also opaque strings, but they identify positions in a connection rather than resources.

The generic node(id: ID!) query can refetch supported resources. Resource-specific inputs still require the correct ID type.

Errors

Process every applicable failure channel:

1. HTTP and transport failures report whether the request reached and was accepted by the GraphQL service.
2. Top-level GraphQL errors report parsing, validation, authorization, or field-execution failures. A response can contain both partial data and errors.
3. Many mutations expose typed business errors in their payload. A 200 OK response can still represent a rejected business operation.

Select __typename for typed errors and use it as the dispatch key. Do not parse human-readable messages to control application behavior.

Shared search filtering is documented in the search query language. Storefront filter construction is covered in facets.