Storefront request context

Storefront results are contextual. The same product can be visible, priced, taxed, translated, and available differently depending on the request and customer.

Context fields

  • storeId selects the store and its distribution, price, supply, checkout, and rounding configuration.
  • priceChannelId selects a market or price list when prices are scoped to a price channel.
  • priceCurrency selects the desired currency.
  • priceCountry participates in country-specific price selection.
  • locale selects localized content.
  • The customer bearer token adds customer identity and group context.

Not every query requires every argument, but a production storefront should derive them from one canonical context object and reuse that object for product lists, product detail, cart creation, and checkout.

Keep catalog and cart aligned

When creating a cart, pass the same storeId, priceChannelId, currency, and country used for catalog queries. A mismatch can produce a different price, no eligible price, different shipping options, or tax recalculation.

Persist the selected market context alongside the cart ID. If a shopper changes market or currency, create or deliberately update the cart and re-read its lines and totals instead of changing only the UI formatter.

Customer context

Anonymous catalog and cart flows can omit customer identity. For signed-in shoppers, send Authorization: Bearer <customer-access-token> on account operations and customer-aware commerce requests. Customer groups can affect prices, discounts, shipping methods, and payment gateways.

Do not accept arbitrary store or channel IDs from an untrusted URL without validating them against the markets your storefront supports. Server-rendered applications should construct context on the server and pass only the public values needed by client code.

Caching

Include every context dimension that can change the response in the cache key: store, price channel, currency, country, locale, and customer segment where relevant. Never share authenticated customer responses through a public cache.

Cursor values also belong to their original filters, sort, and context. Discard pagination state when any of those inputs changes.