GraphQL reference
On this page
- How data reaches a block
- 1. data() helpers, collected into the page call
- 2. load() and ctx.query
- 3. useQuery in the browser, via /_bp/q
- 4. gql()
- 5. Developer tokens
- Which path allows which operation
- Helpers and their operations
- Operations
- Query productGridProducts
- Query storeProfile
- Query storeHome
- Query categoryTree
- Query navigationMenu
- Query productDetail
- Query productSuggestions
- Query productSearch
- Query categoryTreeWithFeatured
- Query categoryFilters
- Query storePromotions
- Query productFrames
- Query gemCertificate
- Query customerMe
- Query customerOrders
- Query customerOrderDetail
- Query customerSavedAddresses
- Query customerWishlist
- Types
- ProductGridResult
- Product
- Money
- Image
- CollectionSummary
- ProductBrowseFacet
- ProductBrowseFacetValue
- PriceRange
- ProductBrowseFilters
- AttributeFilterInput
- StoreProfile
- StoreAnnouncement
- SocialLink
- StorePolicyLinks
- StoreAddress
- PaymentMethodKind
- StoreHome
- HomeHeroBanner
- HomeTestimonial
- HomeFeaturedCollection
- CategoryTreeResult
- Category
- NavigationMenu
- NavigationItem
- NavLinkKind
- ProductDetail
- ProductVariant
- VariantOption
- ProductSpec
- BreadcrumbItem
- ProductSeo
- ProductRating
- ProductReview
- ProductShipping
- ProductStock
- ProductSuggestionsResult
- ProductSearchResult
- SearchFacet
- SearchFacetValue
- SearchFilters
- CategoryTreeWithFeaturedResult
- CategoryWithFeatured
- CategoryFilterDef
- StorePromotion
- PromotionTier
- ProductFramesResult
- ProductFrame
- GemCertificate
- GemCertAuthority
- CustomerProfile
- CustomerOrderList
- CustomerOrder
- CustomerOrderItem
- CustomerShipment
- CustomerAddressList
- CustomerAddress
- CustomerWishlistResult
- CustomerWishlistItem
- WishlistProduct
- Rules for gql()
- Known differences
Where a block's data comes from, and every field you can use. Blocks never talk to GraphQL directly: the data helpers, load()'s ctx.query, useQuery and gql() all end up as one of the storefront operations below, run against the storefront GraphQL schema. Public operations run without the shopper's cookie; the customer* operations run as the shopper.
This page is generated. The operations, variables, result shapes, types, nullability, cache hints and the "which path allows which op" table are read from the code: the schema the backend executes (apps/backend/crates/bp-graphql/src/sdl/storefront.graphql), the SDK's documents (packages/theme-runtime/src/operations.ts, OPERATIONS), the need kinds (packages/theme/src/needs.ts), the helpers (packages/theme/src/data.ts) and their TypeScript types (packages/theme/src/types/storefront.ts), the browser set (packages/theme/src/client/query.ts), the developer-token set (apps/backend/crates/bp-svc-stores/src/dev_tokens.rs) and the Rust need kinds (apps/backend/crates/bp-svc-storefront-page/src/kinds.rs). Field descriptions, per-operation behaviour and the prose are hand-written (packages/cli/scripts/docs/notes/graphql.ts). The Known differences are computed, plus a few hand-written ones.
Contents: How data reaches a block · Which path allows which operation · Helpers and their operations · Operations · Types · Rules for gql() · Known differences
How data reaches a block
There are four ways to ask for data, and a fifth thing (developer tokens) that narrows all of them while you develop.
1. data() helpers, collected into the page call
data() returns needs such as products({ collection, first: 8 }). Nothing is fetched by the helper. At build time a block whose data() only passes props and route values through gets a static template; the storefront sends every block's template with the page request (POST /_internal/storefront/page), and the Rust page endpoint substitutes the saved props and the route, maps each need to its operation (the table in Helpers and their operations) and runs them, deduplicated, in one round before the page renders. A runtime block (one whose data() branches or computes) has its data() called by the storefront renderer per request, which runs the same documents itself: one extra round.
- A need whose required argument is
nullorundefinedis skipped and resolves tonull(no request). - Each operation has 3 s. A failure, a GraphQL error or a timeout gives
nulland marks the page degraded. - Identical needs (same operation, same variables) run once per page, even across blocks.
- The result your
renderreceives is the operation's top-level field (data.productGridProducts), ornull.
The guide is Data.
2. load() and ctx.query
load(ctx) runs on the server for every request. ctx.query(op, vars) runs one operation by name, with the document from OPERATIONS. A public operation is sent without the shopper's cookie (their IP is forwarded), so its answer is the same for every shopper and the page stays cacheable. A customer* operation runs as the shopper: their cookie is forwarded, it answers for the signed-in shopper, and the page is sent private, no-store. Once load() has returned (or timed out), ctx.query resolves to null without a request. The names it accepts are OP_NAMES (packages/theme/src/ops.ts): the 8 helper operations plus categoryTreeWithFeatured, categoryFilters, storePromotions, productFrames, gemCertificate, customerMe, customerOrders, customerOrderDetail, customerSavedAddresses, customerWishlist. The variables are the operation's own ({ handle } for productDetail, not a helper argument such as first). An operation whose document declares $storeSlug gets the current store when you leave it out. An unknown name, an error or a timeout (5 s) resolves to null. load() is never cached.
3. useQuery in the browser, via /_bp/q
An island calls useQuery(op, vars) (or fetchQuery) from @bizzpocket/theme/client. It requests GET /_bp/q/<op>?v=<variables as JSON> on the storefront's own host, which runs the operation's OPERATIONS document and answers { "data": <the top-level field> }. Only BROWSER_QUERY_OPS are served (public, read-only catalogue and store data; a customer* operation or a mutation is a 404, even if the list grew by mistake). The operation runs without the shopper's session and the answer is public, max-age=30, stale-while-revalidate=60 whether or not the request has a cookie. The variables must be a JSON object of at most 4096 bytes, and storeSlug is always the store being shown. Errors are bare codes (NOT_FOUND, BAD_VARS, VARS_TOO_LARGE, UPSTREAM). Details: Fetching from the browser and useQuery().
4. gql()
gql<T>(document, variables?) is a need like the helpers, with a document you write. In a static block the page endpoint runs it with the rest of the page; in a runtime block the renderer runs it, without the shopper's cookie when every top-level field is a public operation, else as the shopper (and the page is personal). Its result is the value of the document's single root field (or the whole data object when it selects several). Use it for fields the SDK's documents do not select (see "Not selected" under each operation) or for a different shape. Rules: Rules for gql().
5. Developer tokens
bizzpocket dev --store <slug> with BIZZPOCKET_DEV_TOKEN renders against a real store with a per-store developer token (header x-bp-dev-token). Both the page endpoint and the storefront GraphQL entry then run only documents whose root fields are all in DEV_TOKEN_OPS (apps/backend/crates/bp-svc-stores/src/dev_tokens.rs), the same 13 operations as the browser set. Every storeSlug argument must be the token's store (a missing $storeSlug variable is filled with it; a literal or default naming another store is refused). At most 32 operations run per page call and the token has 120 units a minute. So during development a load() that calls customerMe, or a gql() selecting a root field outside the set, resolves to null. See Developer tokens.
Which path allows which operation
"helper" names the data() helper that maps to the operation. gql() may select any of these root fields (and the schema's others) except with a developer token, where the last column applies.
| Operation | data() helper |
ctx.query (load()) |
useQuery (browser) |
Developer token | Root cost |
|---|---|---|---|---|---|
productGridProducts |
products() |
yes | yes | yes | 10 |
storeProfile |
store() |
yes | yes | yes | 3 |
storeHome |
home() |
yes | yes | yes | 3 |
categoryTree |
categories() |
yes | yes | yes | 5 |
navigationMenu |
menu() |
yes | yes | yes | 3 |
productDetail |
product() |
yes | yes | yes | 5 |
productSuggestions |
related() |
yes | yes | yes | 5 |
productSearch |
search() |
yes | yes | yes | 15 |
categoryTreeWithFeatured |
no | yes | yes | yes | 10 |
categoryFilters |
no | yes | yes | yes | 5 |
storePromotions |
no | yes | yes | yes | 1 |
productFrames |
no | yes | yes | yes | 1 |
gemCertificate |
no | yes | yes | yes | 1 |
customerMe |
no | yes | no | no | 1 |
customerOrders |
no | yes | no | no | 5 |
customerOrderDetail |
no | yes | no | no | 1 |
customerSavedAddresses |
no | yes | no | no | 1 |
customerWishlist |
no | yes | no | no | 5 |
Sources: NEED_KINDS (packages/theme/src/needs.ts) and the Rust kinds (apps/backend/crates/bp-svc-storefront-page/src/kinds.rs), OP_NAMES (packages/theme/src/ops.ts), BROWSER_QUERY_OPS (packages/theme/src/client/query.ts, filtered by BROWSER_OPS in packages/theme-runtime/src/operations.ts), DEV_TOKEN_OPS (apps/backend/crates/bp-svc-stores/src/dev_tokens.rs). "Root cost" is the operation's weight in the query-cost limit (apps/backend/crates/bp-graphql/src/plugins/query_protection.rs): one document may spend 50 on root fields.
Helpers and their operations
Import the helpers from @bizzpocket/theme. Each returns a need for one operation; * marks a required argument (a need with it unset resolves to null).
| Helper | Operation | Arguments → variables | Result type (TypeScript) |
|---|---|---|---|
products({ collection?, first*, sort?, page?, filters? }) |
productGridProducts |
collection → $collection, first → $limit, sort → $sort, page → $page, filters → $filters |
ProductGridResult | null |
product({ handle* }) |
productDetail |
handle → $handle |
ProductDetail | null |
related({ productId*, first* }) |
productSuggestions |
productId → $productId, first → $limit |
ProductSuggestionsResult | null |
categories({ depth* }) |
categoryTree |
depth → $depth |
CategoryTree | null |
menu({ handle* }) |
navigationMenu |
handle → $handle |
NavigationMenu | null |
store() |
storeProfile |
$storeSlug ← the store being shown |
StoreProfile | null |
home() |
storeHome |
$storeSlug ← the store being shown |
StoreHome | null |
search({ q*, first?, page? }) |
productSearch |
q → $q, first → $limit, page → $page |
ProductSearchResult | null |
gql(document, variables?) |
your document | variables are sent as the document's variables |
T | null |
The result type is the one the helper declares in @bizzpocket/theme; the shape that really arrives is the operation's result below (see Known differences where they disagree).
Operations
Each operation below is one root field of the storefront schema, with the document the SDK sends. The document is shown formatted; the SDK sends it on one line, as written in OPERATIONS. Under "Result", each row is a field the document selects (a[].b is field b of each item of list a), with its GraphQL type; "Null" says whether the field itself can be null. "Not selected" lists the schema fields the document leaves out: reach them with your own gql() document.
Query productGridProducts
A page of products: a whole collection or category, the whole catalogue, or a filtered selection. The workhorse of product grids, rails and collection pages.
| Returns | ProductGridResult (can be null) |
| Reached by | products() in data(), ctx.query, useQuery, developer token |
| Cache hint | 60 s, public |
| Root cost | 10 |
limitis clamped to 1..100;pagestarts at 1 (anything lower reads as 1).collectionSlugis matched against a collection first, then a category (with its sub-categories). Left out, the whole active catalogue is browsed. A slug the store never created that names a common shelf (featured,new-arrivals,best-sellers,sale,all...) shows the featured or newest products instead of an empty grid.sort:price-asc,price-desc; anything else (or nothing) is newest first.facetsandpriceRangeare only computed when the document selects them.- In
filters, a non-emptysizereplacescolor(only one of the two applies).handleswins overfeatured.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$collection |
String |
no | collectionSlug |
products({ collection }) |
|
$page |
Int |
no | page |
products({ page }) |
|
$limit |
Int! |
yes | limit |
products({ first }) |
|
$sort |
String |
no | sort |
products({ sort }) |
|
$filters |
ProductBrowseFilters |
no | filters |
products({ filters }) |
Document
query productGridProducts($collection: String, $page: Int, $limit: Int!, $sort: String, $filters: ProductBrowseFilters) {
productGridProducts(collectionSlug: $collection, page: $page, limit: $limit, sort: $sort, filters: $filters) {
collection {
slug title description
}
products {
id handle title
price {
amount currency
}
compareAtPrice {
amount currency
}
image {
src alt
}
}
total page totalPages
facets {
name
values {
label count value
}
}
priceRange {
min max
}
}
}Result (data.productGridProducts)
| Path | Type | Null |
|---|---|---|
collection |
CollectionSummary |
yes |
collection.slug |
String! |
no |
collection.title |
String! |
no |
collection.description |
String |
yes |
products |
[Product!]! |
no |
products[].id |
ID! |
no |
products[].handle |
String! |
no |
products[].title |
String! |
no |
products[].price |
Money! |
no |
products[].price.amount |
Float! |
no |
products[].price.currency |
String! |
no |
products[].compareAtPrice |
Money |
yes |
products[].compareAtPrice.amount |
Float! |
no |
products[].compareAtPrice.currency |
String! |
no |
products[].image |
Image |
yes |
products[].image.src |
String! |
no |
products[].image.alt |
String! |
no |
total |
Int! |
no |
page |
Int! |
no |
totalPages |
Int! |
no |
facets |
[ProductBrowseFacet!]! |
no |
facets[].name |
String! |
no |
facets[].values |
[ProductBrowseFacetValue!]! |
no |
facets[].values[].label |
String! |
no |
facets[].values[].count |
Int! |
no |
facets[].values[].value |
String! |
no |
priceRange |
PriceRange |
yes |
priceRange.min |
Float! |
no |
priceRange.max |
Float! |
no |
Not selected: products[].isSample.
Query storeProfile
The store's identity and contact details: name, logo, currency, announcements, social links, policies, address and accepted payment methods. One request powers a header and a footer.
| Returns | StoreProfile (can be null) |
| Reached by | store() in data(), ctx.query, useQuery, developer token |
| Cache hint | 300 s, public |
| Root cost | 3 |
- The SDK fills
storeSlugwith the store being shown; you never pass it.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$storeSlug |
String! |
yes | storeSlug |
the store being shown (SDK) |
Arguments of storeProfile this document does not pass: previewToken: String.
Document
query storeProfile($storeSlug: String!) {
storeProfile(storeSlug: $storeSlug) {
name logoUrl phone email currency
announcement {
title message link linkText
}
announcements {
id title message link linkText type position backgroundColor textColor imageUrl imageAlt
}
freeShippingThreshold paymentMethods supportEmail supportPhone whatsappNumber
socialLinks {
platform url
}
policies {
privacyPolicy termsAndConditions returnPolicy refundPolicy shippingPolicy
cancellationPolicy cookiePolicy disclaimerPolicy
}
address {
line city state country pincode
}
}
}Result (data.storeProfile)
| Path | Type | Null |
|---|---|---|
name |
String! |
no |
logoUrl |
String |
yes |
phone |
String |
yes |
email |
String |
yes |
currency |
String! |
no |
announcement |
StoreAnnouncement |
yes |
announcement.title |
String! |
no |
announcement.message |
String |
yes |
announcement.link |
String |
yes |
announcement.linkText |
String |
yes |
announcements |
[StoreAnnouncement!]! |
no |
announcements[].id |
ID |
yes |
announcements[].title |
String! |
no |
announcements[].message |
String |
yes |
announcements[].link |
String |
yes |
announcements[].linkText |
String |
yes |
announcements[].type |
String |
yes |
announcements[].position |
String |
yes |
announcements[].backgroundColor |
String |
yes |
announcements[].textColor |
String |
yes |
announcements[].imageUrl |
String |
yes |
announcements[].imageAlt |
String |
yes |
freeShippingThreshold |
Float |
yes |
paymentMethods |
[PaymentMethodKind!]! |
no |
supportEmail |
String |
yes |
supportPhone |
String |
yes |
whatsappNumber |
String |
yes |
socialLinks |
[SocialLink!]! |
no |
socialLinks[].platform |
String! |
no |
socialLinks[].url |
String! |
no |
policies |
StorePolicyLinks |
yes |
policies.privacyPolicy |
String |
yes |
policies.termsAndConditions |
String |
yes |
policies.returnPolicy |
String |
yes |
policies.refundPolicy |
String |
yes |
policies.shippingPolicy |
String |
yes |
policies.cancellationPolicy |
String |
yes |
policies.cookiePolicy |
String |
yes |
policies.disclaimerPolicy |
String |
yes |
address |
StoreAddress |
yes |
address.line |
String |
yes |
address.city |
String |
yes |
address.state |
String |
yes |
address.country |
String |
yes |
address.pincode |
String |
yes |
Not selected: announcement.id, announcement.type, announcement.position, announcement.backgroundColor, announcement.textColor, announcement.imageUrl, announcement.imageAlt.
Query storeHome
The seller's home page settings: hero banners, section titles and switches, testimonials and featured collections. Products are not in it: fetch them with productGridProducts.
| Returns | StoreHome (can be null) |
| Reached by | home() in data(), ctx.query, useQuery, developer token |
| Cache hint | 120 s, public |
| Root cost | 3 |
- The SDK fills
storeSlugwith the store being shown; you never pass it.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$storeSlug |
String! |
yes | storeSlug |
the store being shown (SDK) |
Arguments of storeHome this document does not pass: previewToken: String.
Document
query storeHome($storeSlug: String!) {
storeHome(storeSlug: $storeSlug) {
heroEnabled
heroBanners {
image title subtitle buttonText buttonLink
}
featuredEnabled featuredTitle categoriesEnabled categoriesTitle newArrivalsEnabled
newArrivalsTitle testimonialsEnabled
testimonials {
name avatar rating text role
}
featuredCollections {
image title href slug subtitle
}
announcement
}
}Result (data.storeHome)
| Path | Type | Null |
|---|---|---|
heroEnabled |
Boolean! |
no |
heroBanners |
[HomeHeroBanner!]! |
no |
heroBanners[].image |
String! |
no |
heroBanners[].title |
String |
yes |
heroBanners[].subtitle |
String |
yes |
heroBanners[].buttonText |
String |
yes |
heroBanners[].buttonLink |
String |
yes |
featuredEnabled |
Boolean! |
no |
featuredTitle |
String! |
no |
categoriesEnabled |
Boolean! |
no |
categoriesTitle |
String! |
no |
newArrivalsEnabled |
Boolean! |
no |
newArrivalsTitle |
String! |
no |
testimonialsEnabled |
Boolean! |
no |
testimonials |
[HomeTestimonial!]! |
no |
testimonials[].name |
String! |
no |
testimonials[].avatar |
String |
yes |
testimonials[].rating |
Int! |
no |
testimonials[].text |
String! |
no |
testimonials[].role |
String |
yes |
featuredCollections |
[HomeFeaturedCollection!]! |
no |
featuredCollections[].image |
String! |
no |
featuredCollections[].title |
String! |
no |
featuredCollections[].href |
String! |
no |
featuredCollections[].slug |
String! |
no |
featuredCollections[].subtitle |
String |
yes |
announcement |
String |
yes |
Query categoryTree
The store's active categories as a tree.
| Returns | CategoryTreeResult (can be null) |
| Reached by | categories() in data(), ctx.query, useQuery, developer token |
| Cache hint | 300 s, public |
| Root cost | 5 |
depthis clamped to 1..5.- The SDK document selects three levels (
categories, theirchildren, and theirs). A deeper tree needs your owngql()document.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$depth |
Int! |
yes | depth |
2 |
categories({ depth }) |
Document
query categoryTree($depth: Int!) {
categoryTree(depth: $depth) {
categories {
id handle title href image
children {
id handle title href image
children {
id handle title href image
}
}
}
}
}Result (data.categoryTree)
| Path | Type | Null |
|---|---|---|
categories |
[Category!]! |
no |
categories[].id |
ID! |
no |
categories[].handle |
String! |
no |
categories[].title |
String! |
no |
categories[].href |
String! |
no |
categories[].image |
String |
yes |
categories[].children |
[Category!] |
yes |
categories[].children[].id |
ID! |
no |
categories[].children[].handle |
String! |
no |
categories[].children[].title |
String! |
no |
categories[].children[].href |
String! |
no |
categories[].children[].image |
String |
yes |
categories[].children[].children |
[Category!] |
yes |
categories[].children[].children[].id |
ID! |
no |
categories[].children[].children[].handle |
String! |
no |
categories[].children[].children[].title |
String! |
no |
categories[].children[].children[].href |
String! |
no |
categories[].children[].children[].image |
String |
yes |
Not selected: categories[].children[].children[].children.
Query navigationMenu
A seller-managed navigation menu by handle, with nested items.
| Returns | NavigationMenu (can be null) |
| Reached by | menu() in data(), ctx.query, useQuery, developer token |
| Cache hint | 300 s, public |
| Root cost | 3 |
mainandfooteralways answer: when the seller has not saved them they are generated from the categories and policies (generated: true). Any other handle isnulluntil the seller saves a menu with it.- Links to deleted targets are already removed, and every URL is checked to be safe.
- The SDK document selects three levels of items.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$handle |
String! |
yes | handle |
menu({ handle }) |
Document
query navigationMenu($handle: String!) {
navigationMenu(handle: $handle) {
handle title generated
items {
id label href imageUrl kind
children {
id label href imageUrl kind
children {
id label href imageUrl kind
}
}
}
}
}Result (data.navigationMenu)
| Path | Type | Null |
|---|---|---|
handle |
String! |
no |
title |
String! |
no |
generated |
Boolean! |
no |
items |
[NavigationItem!]! |
no |
items[].id |
ID! |
no |
items[].label |
String! |
no |
items[].href |
String! |
no |
items[].imageUrl |
String |
yes |
items[].kind |
NavLinkKind! |
no |
items[].children |
[NavigationItem!]! |
no |
items[].children[].id |
ID! |
no |
items[].children[].label |
String! |
no |
items[].children[].href |
String! |
no |
items[].children[].imageUrl |
String |
yes |
items[].children[].kind |
NavLinkKind! |
no |
items[].children[].children |
[NavigationItem!]! |
no |
items[].children[].children[].id |
ID! |
no |
items[].children[].children[].label |
String! |
no |
items[].children[].children[].href |
String! |
no |
items[].children[].children[].imageUrl |
String |
yes |
items[].children[].children[].kind |
NavLinkKind! |
no |
Not selected: items[].children[].children[].children.
Query productDetail
One product by handle, with everything a product page shows: description, price, variants, gallery, specs, breadcrumbs, SEO, rating and reviews, stock and shipping facts.
| Returns | ProductDetail (can be null) |
| Reached by | product() in data(), ctx.query, useQuery, developer token |
| Cache hint | 60 s, public |
| Root cost | 5 |
nullwhen no active product has the handle.reviewsholds the newest 20 approved reviews that carry a comment.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$handle |
String! |
yes | handle |
product({ handle }) |
Document
query productDetail($handle: String!) {
productDetail(handle: $handle) {
id handle title description descriptionHtml
price {
amount currency
}
compareAtPrice {
amount currency
}
inStock
variants {
id sku title inStock
price {
amount currency
}
compareAtPrice {
amount currency
}
options {
name value
}
image {
src alt
}
images {
src alt
}
}
images {
src alt
}
primaryImage {
src alt
}
specs {
label value
}
breadcrumbs {
title href
}
seo {
title description canonical ogImage
}
rating {
average count
}
reviews {
name rating comment
}
shortDescription brand gtin sku tags
shipping {
weight weightUnit length width height dimensionUnit
}
stock {
lowStockRemaining allowBackorder
}
}
}Result (data.productDetail)
| Path | Type | Null |
|---|---|---|
id |
ID! |
no |
handle |
String! |
no |
title |
String! |
no |
description |
String! |
no |
descriptionHtml |
String! |
no |
price |
Money! |
no |
price.amount |
Float! |
no |
price.currency |
String! |
no |
compareAtPrice |
Money |
yes |
compareAtPrice.amount |
Float! |
no |
compareAtPrice.currency |
String! |
no |
inStock |
Boolean! |
no |
variants |
[ProductVariant!]! |
no |
variants[].id |
ID! |
no |
variants[].sku |
String! |
no |
variants[].title |
String! |
no |
variants[].inStock |
Boolean! |
no |
variants[].price |
Money! |
no |
variants[].price.amount |
Float! |
no |
variants[].price.currency |
String! |
no |
variants[].compareAtPrice |
Money |
yes |
variants[].compareAtPrice.amount |
Float! |
no |
variants[].compareAtPrice.currency |
String! |
no |
variants[].options |
[VariantOption!]! |
no |
variants[].options[].name |
String! |
no |
variants[].options[].value |
String! |
no |
variants[].image |
Image |
yes |
variants[].image.src |
String! |
no |
variants[].image.alt |
String! |
no |
variants[].images |
[Image!]! |
no |
variants[].images[].src |
String! |
no |
variants[].images[].alt |
String! |
no |
images |
[Image!]! |
no |
images[].src |
String! |
no |
images[].alt |
String! |
no |
primaryImage |
Image |
yes |
primaryImage.src |
String! |
no |
primaryImage.alt |
String! |
no |
specs |
[ProductSpec!] |
yes |
specs[].label |
String! |
no |
specs[].value |
String! |
no |
breadcrumbs |
[BreadcrumbItem!]! |
no |
breadcrumbs[].title |
String! |
no |
breadcrumbs[].href |
String! |
no |
seo |
ProductSeo |
yes |
seo.title |
String |
yes |
seo.description |
String |
yes |
seo.canonical |
String |
yes |
seo.ogImage |
String |
yes |
rating |
ProductRating |
yes |
rating.average |
Float! |
no |
rating.count |
Int! |
no |
reviews |
[ProductReview!] |
yes |
reviews[].name |
String! |
no |
reviews[].rating |
Float! |
no |
reviews[].comment |
String! |
no |
shortDescription |
String |
yes |
brand |
String |
yes |
gtin |
String |
yes |
sku |
String |
yes |
tags |
[String!]! |
no |
shipping |
ProductShipping |
yes |
shipping.weight |
Float |
yes |
shipping.weightUnit |
String |
yes |
shipping.length |
Float |
yes |
shipping.width |
Float |
yes |
shipping.height |
Float |
yes |
shipping.dimensionUnit |
String |
yes |
stock |
ProductStock |
yes |
stock.lowStockRemaining |
Int |
yes |
stock.allowBackorder |
Boolean! |
no |
Not selected: isSample.
Query productSuggestions
"You may also like" products for a product: active, in-stock products of the same category (featured first, then newest), topped up from the rest of the store when the category is short.
| Returns | ProductSuggestionsResult! (never null) |
| Reached by | related() in data(), ctx.query, useQuery, developer token |
| Cache hint | 300 s, public |
| Root cost | 5 |
limitis clamped to 1..24.- The product itself is never included. An unknown product id gives an empty list.
related()resolves to this object (ProductSuggestionsResult), not a list: read.products.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$productId |
ID! |
yes | productId |
related({ productId }) |
|
$limit |
Int! |
yes | limit |
8 |
related({ first }) |
Document
query productSuggestions($productId: ID!, $limit: Int!) {
productSuggestions(productId: $productId, limit: $limit) {
products {
id handle title
price {
amount currency
}
compareAtPrice {
amount currency
}
image {
src alt
}
}
}
}Result (data.productSuggestions)
| Path | Type | Null |
|---|---|---|
products |
[Product!]! |
no |
products[].id |
ID! |
no |
products[].handle |
String! |
no |
products[].title |
String! |
no |
products[].price |
Money! |
no |
products[].price.amount |
Float! |
no |
products[].price.currency |
String! |
no |
products[].compareAtPrice |
Money |
yes |
products[].compareAtPrice.amount |
Float! |
no |
products[].compareAtPrice.currency |
String! |
no |
products[].image |
Image |
yes |
products[].image.src |
String! |
no |
products[].image.alt |
String! |
no |
Not selected: products[].isSample.
Query productSearch
Full-text product search over the store's active catalogue, with facets.
| Returns | ProductSearchResult! (never null) |
| Reached by | search() in data(), ctx.query, useQuery, developer token |
| Cache hint | not cached (private) |
| Root cost | 15 |
limitdefaults to 20 and is clamped to 1..100;pagestarts at 1.- Answers are never shared between shoppers (
PRIVATE, max age 0): a search is personal.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$q |
String! |
yes | q |
search({ q }) |
|
$page |
Int |
no | page |
1 |
search({ page }) |
$limit |
Int |
no | limit |
20 |
search({ first }) |
$filters |
SearchFilters |
no | filters |
Document
query productSearch($q: String!, $page: Int, $limit: Int, $filters: SearchFilters) {
productSearch(q: $q, page: $page, limit: $limit, filters: $filters) {
hits {
id handle title
price {
amount currency
}
compareAtPrice {
amount currency
}
image {
src alt
}
}
total
facets {
name
values {
label count value
}
}
}
}Result (data.productSearch)
| Path | Type | Null |
|---|---|---|
hits |
[Product!]! |
no |
hits[].id |
ID! |
no |
hits[].handle |
String! |
no |
hits[].title |
String! |
no |
hits[].price |
Money! |
no |
hits[].price.amount |
Float! |
no |
hits[].price.currency |
String! |
no |
hits[].compareAtPrice |
Money |
yes |
hits[].compareAtPrice.amount |
Float! |
no |
hits[].compareAtPrice.currency |
String! |
no |
hits[].image |
Image |
yes |
hits[].image.src |
String! |
no |
hits[].image.alt |
String! |
no |
total |
Int! |
no |
facets |
[SearchFacet!]! |
no |
facets[].name |
String! |
no |
facets[].values |
[SearchFacetValue!]! |
no |
facets[].values[].label |
String! |
no |
facets[].values[].count |
Int! |
no |
facets[].values[].value |
String! |
no |
Not selected: hits[].isSample.
Query categoryTreeWithFeatured
The category tree for a mega menu: each category with a banner image and a few featured products, in one request.
| Returns | CategoryTreeWithFeaturedResult (can be null) |
| Reached by | ctx.query, useQuery, developer token |
| Cache hint | 300 s, public |
| Root cost | 10 |
featuredCountis capped at 24 products per category.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$depth |
Int! |
yes | depth |
2 |
|
$featuredCount |
Int! |
yes | featuredCount |
3 |
Document
query categoryTreeWithFeatured($depth: Int!, $featuredCount: Int!) {
categoryTreeWithFeatured(depth: $depth, featuredCount: $featuredCount) {
categories {
id handle title href
featuredImage {
src alt
}
featuredProducts {
id handle title
price {
amount currency
}
compareAtPrice {
amount currency
}
image {
src alt
}
}
children {
id handle title href
featuredImage {
src alt
}
featuredProducts {
id handle title
price {
amount currency
}
image {
src alt
}
}
}
}
}
}Result (data.categoryTreeWithFeatured)
| Path | Type | Null |
|---|---|---|
categories |
[CategoryWithFeatured!]! |
no |
categories[].id |
ID! |
no |
categories[].handle |
String! |
no |
categories[].title |
String! |
no |
categories[].href |
String! |
no |
categories[].featuredImage |
Image |
yes |
categories[].featuredImage.src |
String! |
no |
categories[].featuredImage.alt |
String! |
no |
categories[].featuredProducts |
[Product!]! |
no |
categories[].featuredProducts[].id |
ID! |
no |
categories[].featuredProducts[].handle |
String! |
no |
categories[].featuredProducts[].title |
String! |
no |
categories[].featuredProducts[].price |
Money! |
no |
categories[].featuredProducts[].price.amount |
Float! |
no |
categories[].featuredProducts[].price.currency |
String! |
no |
categories[].featuredProducts[].compareAtPrice |
Money |
yes |
categories[].featuredProducts[].compareAtPrice.amount |
Float! |
no |
categories[].featuredProducts[].compareAtPrice.currency |
String! |
no |
categories[].featuredProducts[].image |
Image |
yes |
categories[].featuredProducts[].image.src |
String! |
no |
categories[].featuredProducts[].image.alt |
String! |
no |
categories[].children |
[CategoryWithFeatured!] |
yes |
categories[].children[].id |
ID! |
no |
categories[].children[].handle |
String! |
no |
categories[].children[].title |
String! |
no |
categories[].children[].href |
String! |
no |
categories[].children[].featuredImage |
Image |
yes |
categories[].children[].featuredImage.src |
String! |
no |
categories[].children[].featuredImage.alt |
String! |
no |
categories[].children[].featuredProducts |
[Product!]! |
no |
categories[].children[].featuredProducts[].id |
ID! |
no |
categories[].children[].featuredProducts[].handle |
String! |
no |
categories[].children[].featuredProducts[].title |
String! |
no |
categories[].children[].featuredProducts[].price |
Money! |
no |
categories[].children[].featuredProducts[].price.amount |
Float! |
no |
categories[].children[].featuredProducts[].price.currency |
String! |
no |
categories[].children[].featuredProducts[].image |
Image |
yes |
categories[].children[].featuredProducts[].image.src |
String! |
no |
categories[].children[].featuredProducts[].image.alt |
String! |
no |
Not selected: categories[].featuredProducts[].isSample, categories[].children[].featuredProducts[].compareAtPrice, categories[].children[].featuredProducts[].isSample, categories[].children[].children.
Query categoryFilters
The filters the seller configured for a category (or for the store), to build a filter rail. Feed a selection back into productGridProducts as filters.attributes.
| Returns | [CategoryFilterDef!]! (never null) |
| Reached by | ctx.query, useQuery, developer token |
| Cache hint | 300 s, public |
| Root cost | 5 |
- An unknown store or category, or a malformed configuration, gives
[], never an error: fall back to your own price / colour / size filters. - The SDK fills
storeSlugwith the store being shown when you leave it out.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$storeSlug |
String! |
yes | storeSlug |
the store being shown (SDK) | |
$categoryHandle |
String |
no | categoryHandle |
Document
query categoryFilters($storeSlug: String!, $categoryHandle: String) {
categoryFilters(storeSlug: $storeSlug, categoryHandle: $categoryHandle) {
name key type options min max
}
}Result (data.categoryFilters)
| Path | Type | Null |
|---|---|---|
[].name |
String! |
no |
[].key |
String! |
no |
[].type |
String! |
no |
[].options |
[String!] |
yes |
[].min |
Float |
yes |
[].max |
Float |
yes |
Query storePromotions
The coupons the seller chose to advertise that are valid now, newest first.
| Returns | [StorePromotion!]! (never null) |
| Reached by | ctx.query, useQuery, developer token |
| Cache hint | 120 s, public |
| Root cost | 1 |
limitdefaults to 6 and is clamped to 1..20.- Empty when the store advertises none, never
null.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$limit |
Int |
no | limit |
Document
query storePromotions($limit: Int) {
storePromotions(limit: $limit) {
code description type value currency minOrderAmount maxDiscount validUntil buyQuantity
getQuantity getDiscountPercent spendThreshold getAmount getPercent
tiers {
minSubtotal kind value
}
}
}Result (data.storePromotions)
| Path | Type | Null |
|---|---|---|
[].code |
String! |
no |
[].description |
String |
yes |
[].type |
String! |
no |
[].value |
Float! |
no |
[].currency |
String |
yes |
[].minOrderAmount |
Float |
yes |
[].maxDiscount |
Float |
yes |
[].validUntil |
String |
yes |
[].buyQuantity |
Int |
yes |
[].getQuantity |
Int |
yes |
[].getDiscountPercent |
Float |
yes |
[].spendThreshold |
Float |
yes |
[].getAmount |
Float |
yes |
[].getPercent |
Float |
yes |
[].tiers |
[PromotionTier!] |
yes |
[].tiers[].minSubtotal |
Float! |
no |
[].tiers[].kind |
String! |
no |
[].tiers[].value |
Float! |
no |
Query productFrames
A product's 360° viewer frames.
| Returns | ProductFramesResult (can be null) |
| Reached by | ctx.query, useQuery, developer token |
| Cache hint | 3600 s, public |
| Root cost | 1 |
frameCountis lowered to the number of captured frames (at least 1); fewer frames are sampled evenly.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$productId |
ID! |
yes | productId |
||
$frameCount |
Int! |
yes | frameCount |
36 |
Document
query productFrames($productId: ID!, $frameCount: Int!) {
productFrames(productId: $productId, frameCount: $frameCount) {
productId frameCount
frames {
index src width height
}
preview {
src alt
}
}
}Result (data.productFrames)
| Path | Type | Null |
|---|---|---|
productId |
ID! |
no |
frameCount |
Int! |
no |
frames |
[ProductFrame!]! |
no |
frames[].index |
Int! |
no |
frames[].src |
String! |
no |
frames[].width |
Int! |
no |
frames[].height |
Int! |
no |
preview |
Image |
yes |
preview.src |
String! |
no |
preview.alt |
String! |
no |
Query gemCertificate
A gemstone product's grading certificate (GIA, IGI...).
| Returns | GemCertificate (can be null) |
| Reached by | ctx.query, useQuery, developer token |
| Cache hint | 86400 s, public |
| Root cost | 1 |
nullwhen the product has none.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$productId |
ID! |
yes | productId |
Document
query gemCertificate($productId: ID!) {
gemCertificate(productId: $productId) {
productId certificateNumber issuingAuthority issuedAt reportUrl shape caratWeight color
clarity cut polish symmetry fluorescence measurements comments imageUrl
}
}Result (data.gemCertificate)
| Path | Type | Null |
|---|---|---|
productId |
ID! |
no |
certificateNumber |
String! |
no |
issuingAuthority |
GemCertAuthority! |
no |
issuedAt |
String! |
no |
reportUrl |
String |
yes |
shape |
String |
yes |
caratWeight |
Float |
yes |
color |
String |
yes |
clarity |
String |
yes |
cut |
String |
yes |
polish |
String |
yes |
symmetry |
String |
yes |
fluorescence |
String |
yes |
measurements |
String |
yes |
comments |
String |
yes |
imageUrl |
String |
yes |
Query customerMe
The signed-in shopper's profile.
| Returns | CustomerProfile (can be null) |
| Reached by | ctx.query |
| Cache hint | not cached (private) |
| Root cost | 1 |
nullwhen nobody is signed in. Shopper data:load()only.
Variables: none.
Document
query customerMe {
customerMe {
id email phone firstName lastName gender dob marketingEmailOptIn marketingSmsOptIn
marketingWhatsappOptIn emailVerifiedAt phoneVerifiedAt lastLoginAt createdAt softDeletedAt
}
}Result (data.customerMe)
| Path | Type | Null |
|---|---|---|
id |
ID! |
no |
email |
String |
yes |
phone |
String |
yes |
firstName |
String |
yes |
lastName |
String |
yes |
gender |
String |
yes |
dob |
String |
yes |
marketingEmailOptIn |
Boolean! |
no |
marketingSmsOptIn |
Boolean! |
no |
marketingWhatsappOptIn |
Boolean! |
no |
emailVerifiedAt |
String |
yes |
phoneVerifiedAt |
String |
yes |
lastLoginAt |
String |
yes |
createdAt |
String! |
no |
softDeletedAt |
String |
yes |
Query customerOrders
The signed-in shopper's orders, newest first, a page at a time.
| Returns | CustomerOrderList! (never null) |
| Reached by | ctx.query |
| Cache hint | not cached (private) |
| Root cost | 5 |
limitdefaults to 10 and is clamped to 1..50;pagestarts at 1.- Nobody signed in: an empty list.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$page |
Int |
no | page |
1 |
|
$limit |
Int |
no | limit |
10 |
|
$status |
String |
no | status |
Document
query customerOrders($page: Int, $limit: Int, $status: String) {
customerOrders(page: $page, limit: $limit, status: $status) {
orders {
id orderNumber status paymentStatus subtotal tax shippingCost discount total currency
shippingName shippingAddress shippingCity shippingState shippingCountry shippingPincode
shippingMethod customerNote couponCode createdAt canReturn canReorder
items {
id productId productName productSlug quantity unitPrice totalPrice colorName sizeName
image
}
shipment {
trackingNumber trackingUrl carrier status estimatedDelivery
}
}
total page totalPages
}
}Result (data.customerOrders)
| Path | Type | Null |
|---|---|---|
orders |
[CustomerOrder!]! |
no |
orders[].id |
ID! |
no |
orders[].orderNumber |
String! |
no |
orders[].status |
String! |
no |
orders[].paymentStatus |
String! |
no |
orders[].subtotal |
Float! |
no |
orders[].tax |
Float! |
no |
orders[].shippingCost |
Float! |
no |
orders[].discount |
Float! |
no |
orders[].total |
Float! |
no |
orders[].currency |
String! |
no |
orders[].shippingName |
String! |
no |
orders[].shippingAddress |
String! |
no |
orders[].shippingCity |
String! |
no |
orders[].shippingState |
String! |
no |
orders[].shippingCountry |
String! |
no |
orders[].shippingPincode |
String! |
no |
orders[].shippingMethod |
String |
yes |
orders[].customerNote |
String |
yes |
orders[].couponCode |
String |
yes |
orders[].createdAt |
String! |
no |
orders[].canReturn |
Boolean! |
no |
orders[].canReorder |
Boolean! |
no |
orders[].items |
[CustomerOrderItem!]! |
no |
orders[].items[].id |
ID! |
no |
orders[].items[].productId |
String! |
no |
orders[].items[].productName |
String! |
no |
orders[].items[].productSlug |
String |
yes |
orders[].items[].quantity |
Int! |
no |
orders[].items[].unitPrice |
Float! |
no |
orders[].items[].totalPrice |
Float! |
no |
orders[].items[].colorName |
String |
yes |
orders[].items[].sizeName |
String |
yes |
orders[].items[].image |
String |
yes |
orders[].shipment |
CustomerShipment |
yes |
orders[].shipment.trackingNumber |
String |
yes |
orders[].shipment.trackingUrl |
String |
yes |
orders[].shipment.carrier |
String |
yes |
orders[].shipment.status |
String |
yes |
orders[].shipment.estimatedDelivery |
String |
yes |
total |
Int! |
no |
page |
Int! |
no |
totalPages |
Int! |
no |
Query customerOrderDetail
One order of the signed-in shopper.
| Returns | CustomerOrder (can be null) |
| Reached by | ctx.query |
| Cache hint | not cached (private) |
| Root cost | 1 |
nullwhen the order is not theirs or nobody is signed in.
Variables
| Variable | Type | Required | Argument | Schema default | Filled from |
|---|---|---|---|---|---|
$orderId |
ID! |
yes | orderId |
Document
query customerOrderDetail($orderId: ID!) {
customerOrderDetail(orderId: $orderId) {
id orderNumber status paymentStatus subtotal tax shippingCost discount total currency
shippingName shippingAddress shippingCity shippingState shippingCountry shippingPincode
shippingMethod customerNote couponCode createdAt canReturn canReorder
items {
id productId productName productSlug quantity unitPrice totalPrice colorName sizeName
image
}
shipment {
trackingNumber trackingUrl carrier status estimatedDelivery
}
}
}Result (data.customerOrderDetail)
| Path | Type | Null |
|---|---|---|
id |
ID! |
no |
orderNumber |
String! |
no |
status |
String! |
no |
paymentStatus |
String! |
no |
subtotal |
Float! |
no |
tax |
Float! |
no |
shippingCost |
Float! |
no |
discount |
Float! |
no |
total |
Float! |
no |
currency |
String! |
no |
shippingName |
String! |
no |
shippingAddress |
String! |
no |
shippingCity |
String! |
no |
shippingState |
String! |
no |
shippingCountry |
String! |
no |
shippingPincode |
String! |
no |
shippingMethod |
String |
yes |
customerNote |
String |
yes |
couponCode |
String |
yes |
createdAt |
String! |
no |
canReturn |
Boolean! |
no |
canReorder |
Boolean! |
no |
items |
[CustomerOrderItem!]! |
no |
items[].id |
ID! |
no |
items[].productId |
String! |
no |
items[].productName |
String! |
no |
items[].productSlug |
String |
yes |
items[].quantity |
Int! |
no |
items[].unitPrice |
Float! |
no |
items[].totalPrice |
Float! |
no |
items[].colorName |
String |
yes |
items[].sizeName |
String |
yes |
items[].image |
String |
yes |
shipment |
CustomerShipment |
yes |
shipment.trackingNumber |
String |
yes |
shipment.trackingUrl |
String |
yes |
shipment.carrier |
String |
yes |
shipment.status |
String |
yes |
shipment.estimatedDelivery |
String |
yes |
Query customerSavedAddresses
The signed-in shopper's saved addresses.
| Returns | CustomerAddressList! (never null) |
| Reached by | ctx.query |
| Cache hint | not cached (private) |
| Root cost | 1 |
Variables: none.
Document
query customerSavedAddresses {
customerSavedAddresses {
addresses {
id label firstName lastName line1 line2 city state country pincode phone isDefault
}
}
}Result (data.customerSavedAddresses)
| Path | Type | Null |
|---|---|---|
addresses |
[CustomerAddress!]! |
no |
addresses[].id |
ID! |
no |
addresses[].label |
String |
yes |
addresses[].firstName |
String! |
no |
addresses[].lastName |
String! |
no |
addresses[].line1 |
String! |
no |
addresses[].line2 |
String |
yes |
addresses[].city |
String! |
no |
addresses[].state |
String! |
no |
addresses[].country |
String! |
no |
addresses[].pincode |
String! |
no |
addresses[].phone |
String |
yes |
addresses[].isDefault |
Boolean! |
no |
Query customerWishlist
The signed-in shopper's wishlist.
| Returns | CustomerWishlistResult! (never null) |
| Reached by | ctx.query |
| Cache hint | not cached (private) |
| Root cost | 5 |
Variables: none.
Document
query customerWishlist {
customerWishlist {
items {
productId addedAt
product {
id handle title
price {
amount currency
}
image {
src alt
}
inStock
}
}
}
}Result (data.customerWishlist)
| Path | Type | Null |
|---|---|---|
items |
[CustomerWishlistItem!]! |
no |
items[].productId |
String! |
no |
items[].addedAt |
String! |
no |
items[].product |
WishlistProduct |
yes |
items[].product.id |
ID! |
no |
items[].product.handle |
String! |
no |
items[].product.title |
String! |
no |
items[].product.price |
Money! |
no |
items[].product.price.amount |
Float! |
no |
items[].product.price.currency |
String! |
no |
items[].product.image |
Image |
yes |
items[].product.image.src |
String! |
no |
items[].product.image.alt |
String! |
no |
items[].product.inStock |
Boolean! |
no |
Types
Every type reachable from the operations above, with every field the schema has (selected by the SDK or not). "Null" says whether the field can be null; list item nullability is in the type ([Product!]!: never null, items never null). The TypeScript name is the type exported by @bizzpocket/theme, where there is one.
ProductGridResult
Object. A page of products and what the shopper can filter it by. TypeScript: ProductGridResult. Used by productGridProducts.
| Field | Type | Null | Description |
|---|---|---|---|
products |
[Product!]! |
no | The products of this page. |
collection |
CollectionSummary |
yes | The collection or category the grid is scoped to; null for the whole catalogue or a slug that matched nothing. |
total |
Int! |
no | Products matching, over all pages. |
page |
Int! |
no | This page number (from 1). |
totalPages |
Int! |
no | Number of pages at this limit. |
facets |
[ProductBrowseFacet!]! |
no | Filter dimensions (colour, size, seller attributes) with counts. |
priceRange |
PriceRange |
yes | Lowest and highest price in the scope and filters, ignoring the price filter itself (so a chosen band does not collapse the others). null when nothing matches. Build price bands from it. |
Product
Object. A product as listed in grids, rails, search and menus. TypeScript: Product. Used by productGridProducts, productSuggestions, productSearch, categoryTreeWithFeatured.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
handle |
String! |
no | URL name (slug). Pass it to product({ handle }) / the product page route. |
title |
String! |
no | Product name. |
price |
Money! |
no | Price (of the cheapest variant for a product with variants). |
compareAtPrice |
Money |
yes | The "was" price, when the seller set one above price; else null. |
image |
Image |
yes | Primary image; null when the product has none. |
isSample |
Boolean! |
no | A sample product seeded into a new store so its preview is never empty. It cannot be bought and is removed when the store goes live: badge it "Sample". |
Money
Object. An amount of money. TypeScript: Money. Used by productGridProducts, productDetail, productSuggestions, productSearch, categoryTreeWithFeatured, customerWishlist.
| Field | Type | Null | Description |
|---|---|---|---|
amount |
Float! |
no | Amount in the currency's main unit (499.5, not paise or cents). |
currency |
String! |
no | ISO 4217 code, e.g. INR. |
Image
Object. An image. TypeScript: Image. Used by productGridProducts, productDetail, productSuggestions, productSearch, categoryTreeWithFeatured, productFrames, customerWishlist.
| Field | Type | Null | Description |
|---|---|---|---|
src |
String! |
no | Absolute image URL. |
alt |
String! |
no | Alt text; an empty string when the seller wrote none. |
CollectionSummary
Object. The collection or category a product grid is scoped to. TypeScript: CollectionSummary. Used by productGridProducts.
| Field | Type | Null | Description |
|---|---|---|---|
slug |
String! |
no | Its URL name. |
title |
String! |
no | Its name. |
description |
String |
yes | Its description; null when none. |
ProductBrowseFacet
Object. A filter dimension of a product grid (e.g. colour, size) with its values. TypeScript: ProductBrowseFacet. Used by productGridProducts.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Dimension name; for seller attributes, the attribute key. |
values |
[ProductBrowseFacetValue!]! |
no | Values with product counts, most common first. |
ProductBrowseFacetValue
Object. One value of a grid facet. TypeScript: ProductBrowseFacetValue. Used by productGridProducts.
| Field | Type | Null | Description |
|---|---|---|---|
label |
String! |
no | Text to show. |
value |
String! |
no | Value to send back in filters. |
count |
Int! |
no | Products with this value. |
PriceRange
Object. Lowest and highest price. TypeScript: PriceRange. Used by productGridProducts.
| Field | Type | Null | Description |
|---|---|---|---|
min |
Float! |
no | Lowest price. |
max |
Float! |
no | Highest price. |
ProductBrowseFilters
Input object. Filters for productGridProducts. Every field is optional; a field left out is not applied. Unknown keys are refused by GraphQL validation. TypeScript: ProductBrowseFilters. Used by productGridProducts.
| Field | Type | Null | Default | Description |
|---|---|---|---|---|
priceMin |
Float |
yes | Lowest price, inclusive. | |
priceMax |
Float |
yes | Highest price, inclusive. | |
inStock |
Boolean |
yes | true: only products in stock. false or left out: not applied. |
|
color |
[String!] |
yes | Colour values (case-insensitive). Ignored when size is set. |
|
size |
[String!] |
yes | Size values (case-insensitive). Replaces color when both are set. |
|
attributes |
[AttributeFilterInput!] |
yes | Seller-configured attribute filters (the keys come from categoryFilters). |
|
featured |
Boolean |
yes | true: only the seller's featured products (in the seller's order when no sort is given). false or left out: not applied. |
|
handles |
[String!] |
yes | Exactly these products, by handle, in this order when no sort is given (a block's own product picks, f.products()). Wins over featured. Empty or left out: not applied. |
AttributeFilterInput
Input object. One seller-configured attribute filter. A product matches when any of its variant options (or filled-in specifications) named key has a value in values. TypeScript: AttributeFilterInput. Used by productGridProducts.
| Field | Type | Null | Default | Description |
|---|---|---|---|---|
key |
String! |
no | Attribute key, as CategoryFilterDef.key gives it (case-insensitive). |
|
values |
[String!]! |
no | Accepted values (case-insensitive). |
StoreProfile
Object. The store's identity, contact details and policies. TypeScript: StoreProfile. Used by storeProfile.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Store name. |
logoUrl |
String |
yes | Logo URL; null when none (show the name). |
phone |
String |
yes | Contact phone. |
email |
String |
yes | Contact email. |
currency |
String! |
no | Display currency (ISO 4217, e.g. INR): format money with it. |
announcement |
StoreAnnouncement |
yes | The live header announcement, or null. Kept for older themes: read announcements. |
announcements |
[StoreAnnouncement!]! |
no | Every live announcement, all positions (header, footer, popup), newest first, at most 10. |
freeShippingThreshold |
Float |
yes | Order value from which shipping is free, in the store currency; null when the store has no such offer. |
supportEmail |
String |
yes | Support email. |
supportPhone |
String |
yes | Support phone. |
whatsappNumber |
String |
yes | WhatsApp number. |
socialLinks |
[SocialLink!]! |
no | Social profiles. |
policies |
StorePolicyLinks |
yes | Links to the policy pages. |
address |
StoreAddress |
yes | Business address; parts the seller did not fill in are null. |
paymentMethods |
[PaymentMethodKind!]! |
no | Payment methods the store's checkout accepts right now. [] when none or unknown, never an invented method. |
StoreAnnouncement
Object. A seller announcement (a bar, a footer note or a popup). TypeScript: StoreAnnouncement. Used by storeProfile.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID |
yes | Id; null on the legacy announcement field. |
title |
String! |
no | Headline. |
message |
String |
yes | Body text. |
link |
String |
yes | Link URL. |
linkText |
String |
yes | Link label. |
type |
String |
yes | Seller value, lower-case: info, success, warning, sale, promo... |
position |
String |
yes | header, footer or popup. |
backgroundColor |
String |
yes | Seller colour (#rgb / #rrggbb), else null: keep your palette. |
textColor |
String |
yes | Seller colour (#rgb / #rrggbb), else null: keep your palette. |
imageUrl |
String |
yes | Popup artwork (absolute https URL), else null. |
imageAlt |
String |
yes | Alt text for imageUrl; null means decorative. |
SocialLink
Object. A social profile of the store. TypeScript: SocialLink. Used by storeProfile.
| Field | Type | Null | Description |
|---|---|---|---|
platform |
String! |
no | Platform key, e.g. instagram. |
url |
String! |
no | Profile URL. |
StorePolicyLinks
Object. Links to the store's policy pages; null when the store has none. TypeScript: StorePolicyLinks. Used by storeProfile.
| Field | Type | Null | Description |
|---|---|---|---|
privacyPolicy |
String |
yes | Privacy policy. |
termsAndConditions |
String |
yes | Terms and conditions. |
returnPolicy |
String |
yes | Return policy. |
refundPolicy |
String |
yes | Refund policy. |
shippingPolicy |
String |
yes | Shipping policy. |
cancellationPolicy |
String |
yes | Cancellation policy. |
cookiePolicy |
String |
yes | Cookie policy. |
disclaimerPolicy |
String |
yes | Disclaimer. |
StoreAddress
Object. The business address; each part is null when not filled in. TypeScript: StoreAddress. Used by storeProfile.
| Field | Type | Null | Description |
|---|---|---|---|
line |
String |
yes | Street address. |
city |
String |
yes | City. |
state |
String |
yes | State. |
country |
String |
yes | Country. |
pincode |
String |
yes | Postal code. |
PaymentMethodKind
Enum. A payment method a checkout accepts. TypeScript: PaymentMethodKind. Used by storeProfile.
| Value | Meaning |
|---|---|
UPI |
UPI. |
CARD |
Debit and credit cards. |
NETBANKING |
Net banking. |
WALLET |
Wallets. |
COD |
Cash on delivery. |
StoreHome
Object. The seller's home page settings. TypeScript: StoreHome. Used by storeHome.
| Field | Type | Null | Description |
|---|---|---|---|
heroEnabled |
Boolean! |
no | Show the hero. |
heroBanners |
[HomeHeroBanner!]! |
no | Hero slides. |
featuredEnabled |
Boolean! |
no | Show the featured products section. |
featuredTitle |
String! |
no | Its heading. |
categoriesEnabled |
Boolean! |
no | Show the categories section. |
categoriesTitle |
String! |
no | Its heading. |
newArrivalsEnabled |
Boolean! |
no | Show the new arrivals section. |
newArrivalsTitle |
String! |
no | Its heading. |
testimonialsEnabled |
Boolean! |
no | Show the testimonials section. |
testimonials |
[HomeTestimonial!]! |
no | Testimonials. |
featuredCollections |
[HomeFeaturedCollection!]! |
no | Collections the seller marked as featured, as promo banners. |
announcement |
String |
yes | Home page announcement text; null when none. |
HomeHeroBanner
Object. One hero slide. TypeScript: HomeHeroBanner. Used by storeHome.
| Field | Type | Null | Description |
|---|---|---|---|
image |
String! |
no | Image URL. |
title |
String |
yes | Headline. |
subtitle |
String |
yes | Sub-heading. |
buttonText |
String |
yes | Button label. |
buttonLink |
String |
yes | Button URL. |
HomeTestimonial
Object. One testimonial. TypeScript: HomeTestimonial. Used by storeHome.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Who said it. |
avatar |
String |
yes | Their picture URL. |
rating |
Int! |
no | Stars, 0 to 5. |
text |
String! |
no | The quote. |
role |
String |
yes | Their role or city. |
HomeFeaturedCollection
Object. A featured collection, as a home page promo. TypeScript: HomeFeaturedCollection. Used by storeHome.
| Field | Type | Null | Description |
|---|---|---|---|
image |
String! |
no | Banner image URL. |
title |
String! |
no | Collection name. |
href |
String! |
no | Storefront path of the collection page. |
slug |
String! |
no | Collection URL name (for products({ collection })). |
subtitle |
String |
yes | Short description. |
CategoryTreeResult
Object. The category tree. TypeScript: CategoryTree. Used by categoryTree.
| Field | Type | Null | Description |
|---|---|---|---|
categories |
[Category!]! |
no | Top-level categories. |
Category
Object. A category in the tree. TypeScript: Category. Used by categoryTree.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
handle |
String! |
no | URL name (for products({ collection })). |
title |
String! |
no | Category name. |
href |
String! |
no | Storefront path of the category page. |
image |
String |
yes | Category image URL; null when none. |
children |
[Category!] |
yes | Sub-categories (down to the requested depth). |
NavigationMenu
Object. A navigation menu. TypeScript: NavigationMenu. Used by navigationMenu.
| Field | Type | Null | Description |
|---|---|---|---|
handle |
String! |
no | Menu handle (main, footer, or a seller-chosen one). |
title |
String! |
no | Menu name. |
generated |
Boolean! |
no | true: generated from the categories and policies, the seller has not saved this menu. |
items |
[NavigationItem!]! |
no | Top-level items. |
NavigationItem
Object. One menu item. TypeScript: NavigationLeafItem. Used by navigationMenu.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
label |
String! |
no | Text to show. |
href |
String! |
no | Link (checked to be safe). |
imageUrl |
String |
yes | Image for mega menus; null when none. |
kind |
NavLinkKind! |
no | What it links to. |
children |
[NavigationItem!]! |
no | Sub-items; empty when none. |
NavLinkKind
Enum. What a menu item links to. TypeScript: NavLinkKind. Used by navigationMenu.
| Value | Meaning |
|---|---|
CATEGORY |
A category page. |
COLLECTION |
A collection page. |
PRODUCT |
A product page. |
PAGE |
A content or policy page. |
URL |
Any other URL. |
ProductDetail
Object. One product, for a product page. TypeScript: ProductDetail. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
handle |
String! |
no | URL name. |
title |
String! |
no | Product name. |
description |
String! |
no | Description as plain text. |
descriptionHtml |
String! |
no | Description as sanitized HTML, safe to render. |
price |
Money! |
no | Price. |
compareAtPrice |
Money |
yes | The "was" price, else null. |
inStock |
Boolean! |
no | Can be bought now. |
variants |
[ProductVariant!]! |
no | Every variant; empty for a single-variant product. |
images |
[Image!]! |
no | Gallery, in the seller's order, primary first. |
primaryImage |
Image |
yes | Primary image; null when none. |
specs |
[ProductSpec!] |
yes | Specification rows (label and value): render as a definition list. |
breadcrumbs |
[BreadcrumbItem!]! |
no | Category path to the product. |
seo |
ProductSeo |
yes | SEO metadata. |
rating |
ProductRating |
yes | Average rating and count; null when there are no reviews. |
reviews |
[ProductReview!] |
yes | Approved reviews with a comment, newest first (at most 20). The average is in rating. |
shortDescription |
String |
yes | The seller's one-line summary. |
isSample |
Boolean! |
no | A sample product (see Product.isSample). |
sku |
String |
yes | SKU of a single-variant product (variants carry their own). |
brand |
String |
yes | Brand; null when unset. |
gtin |
String |
yes | GTIN barcode (8, 12, 13 or 14 digits, check digit verified); null when absent or invalid. |
tags |
[String!]! |
no | Seller tags; empty when none. |
shipping |
ProductShipping |
yes | Weight and dimensions. |
stock |
ProductStock |
yes | Stock detail beyond inStock. |
ProductVariant
Object. One variant of a product (a size, a colour...). TypeScript: ProductVariant. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
sku |
String! |
no | SKU. |
title |
String! |
no | Variant name, e.g. M / Red. |
price |
Money! |
no | Price. |
compareAtPrice |
Money |
yes | The "was" price, else null. |
inStock |
Boolean! |
no | Can be bought now. |
options |
[VariantOption!]! |
no | Its option values, one per axis: { name: "Size", value: "M" }. Build swatches and selects from them. |
image |
Image |
yes | Its image; null when none. The first of images. |
images |
[Image!]! |
no | Every image the seller linked to this variant, in gallery order; empty when none. |
VariantOption
Object. One axis value of a variant. TypeScript: VariantOption. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Axis, e.g. Size. |
value |
String! |
no | Value, e.g. M. |
ProductSpec
Object. One specification row. TypeScript: ProductSpec. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
label |
String! |
no | Label, e.g. Material. |
value |
String! |
no | Value. |
BreadcrumbItem
Object. One step of a breadcrumb trail. TypeScript: BreadcrumbItem. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
title |
String! |
no | Text. |
href |
String! |
no | Storefront path. |
ProductSeo
Object. SEO metadata of a product. TypeScript: ProductSeo. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
title |
String |
yes | Page title. |
description |
String |
yes | Meta description. |
canonical |
String |
yes | Canonical URL. |
ogImage |
String |
yes | Social share image URL. |
ProductRating
Object. Aggregate rating. TypeScript: ProductRating. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
average |
Float! |
no | Average stars, 0 to 5. |
count |
Int! |
no | Number of approved reviews. |
ProductReview
Object. One approved review. TypeScript: ProductReview. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Reviewer's name. |
rating |
Float! |
no | Stars, 0 to 5. |
comment |
String! |
no | Review text. |
ProductShipping
Object. Physical facts of a product; each null when not filled in. TypeScript: ProductShipping. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
weight |
Float |
yes | Weight. |
weightUnit |
String |
yes | Unit of weight. |
length |
Float |
yes | Length. |
width |
Float |
yes | Width. |
height |
Float |
yes | Height. |
dimensionUnit |
String |
yes | Unit of the dimensions. |
ProductStock
Object. Availability detail. TypeScript: ProductStock. Used by productDetail.
| Field | Type | Null | Description |
|---|---|---|---|
lowStockRemaining |
Int |
yes | Units left, but only when at or below the seller's low-stock threshold ("Only 3 left"); null otherwise. The full stock level is never public. |
allowBackorder |
Boolean! |
no | The seller accepts orders past zero stock: show "available on backorder". |
ProductSuggestionsResult
Object. Suggested products. TypeScript: ProductSuggestionsResult. Used by productSuggestions.
| Field | Type | Null | Description |
|---|---|---|---|
products |
[Product!]! |
no | The suggestions. |
ProductSearchResult
Object. A page of search results. TypeScript: ProductSearchResult. Used by productSearch.
| Field | Type | Null | Description |
|---|---|---|---|
hits |
[Product!]! |
no | Matching products of this page. |
total |
Int! |
no | Matches over all pages. |
facets |
[SearchFacet!]! |
no | Filter dimensions with counts. |
SearchFacet
Object. A filter dimension of search results. TypeScript: SearchFacet. Used by productSearch.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Dimension name. |
values |
[SearchFacetValue!]! |
no | Values with counts. |
SearchFacetValue
Object. One value of a search facet. TypeScript: SearchFacetValue. Used by productSearch.
| Field | Type | Null | Description |
|---|---|---|---|
label |
String! |
no | Text to show. |
count |
Int! |
no | Matches with this value. |
value |
String! |
no | Value to send back in filters. |
SearchFilters
Input object. Filters for productSearch. Every field is optional; a field left out is not applied. Used by productSearch.
| Field | Type | Null | Default | Description |
|---|---|---|---|---|
priceMin |
Float |
yes | Lowest price, inclusive. | |
priceMax |
Float |
yes | Highest price, inclusive. | |
inStock |
Boolean |
yes | true: only products in stock. |
|
color |
[String!] |
yes | Colour values (case-insensitive). | |
size |
[String!] |
yes | Size values. |
CategoryTreeWithFeaturedResult
Object. The category tree for a mega menu. Used by categoryTreeWithFeatured.
| Field | Type | Null | Description |
|---|---|---|---|
categories |
[CategoryWithFeatured!]! |
no | Top-level categories. |
CategoryWithFeatured
Object. A category with its mega-menu content. Used by categoryTreeWithFeatured.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
handle |
String! |
no | URL name. |
title |
String! |
no | Category name. |
href |
String! |
no | Storefront path of the category page. |
children |
[CategoryWithFeatured!] |
yes | Sub-categories. |
featuredProducts |
[Product!]! |
no | Products for the hover panel (at most featuredCount): the seller's picks, else best-sellers. |
featuredImage |
Image |
yes | Banner image; null when none. |
CategoryFilterDef
Object. One seller-configured filter. Used by categoryFilters.
| Field | Type | Null | Description |
|---|---|---|---|
name |
String! |
no | Label to show. |
key |
String! |
no | Stable key: send it back as AttributeFilterInput.key. |
type |
String! |
no | single, multi, range or boolean. |
options |
[String!] |
yes | Choices, for single and multi. |
min |
Float |
yes | Lower bound, for range. |
max |
Float |
yes | Upper bound, for range. |
StorePromotion
Object. An advertised coupon. Used by storePromotions.
| Field | Type | Null | Description |
|---|---|---|---|
code |
String! |
no | The code a shopper types at checkout. |
description |
String |
yes | The seller's own text; null when none. |
type |
String! |
no | PERCENTAGE, FIXED, FREE_SHIPPING, BUY_X_GET_Y, SPEND_X_GET_Y, TIERED... |
value |
Float! |
no | Discount: a percent for PERCENTAGE, else an amount. |
currency |
String |
yes | Currency of an amount; null for a percentage. |
minOrderAmount |
Float |
yes | Minimum order value, if any. |
maxDiscount |
Float |
yes | Cap on a percentage discount, if any. |
validUntil |
String |
yes | ISO timestamp it ends; null for no end. |
buyQuantity |
Int |
yes | BUY_X_GET_Y: buy this many... |
getQuantity |
Int |
yes | BUY_X_GET_Y: ...get this many. |
getDiscountPercent |
Float |
yes | BUY_X_GET_Y: discount on the free units (100 = free). |
spendThreshold |
Float |
yes | SPEND_X_GET_Y: basket value that unlocks the reward. |
getAmount |
Float |
yes | SPEND_X_GET_Y: flat reward. |
getPercent |
Float |
yes | SPEND_X_GET_Y: percentage reward. |
tiers |
[PromotionTier!] |
yes | TIERED: the spend ladder, lowest first. |
PromotionTier
Object. One step of a tiered promotion. Used by storePromotions.
| Field | Type | Null | Description |
|---|---|---|---|
minSubtotal |
Float! |
no | Basket value from which it applies. |
kind |
String! |
no | PERCENTAGE or FIXED_AMOUNT. |
value |
Float! |
no | Percent or amount. |
ProductFramesResult
Object. A product's 360° frames. Used by productFrames.
| Field | Type | Null | Description |
|---|---|---|---|
productId |
ID! |
no | The product. |
frameCount |
Int! |
no | Frames returned (may be fewer than asked). |
frames |
[ProductFrame!]! |
no | Frames in order; index 0 is the front view. |
preview |
Image |
yes | Still image to show until the frames load. |
ProductFrame
Object. One 360° frame. Used by productFrames.
| Field | Type | Null | Description |
|---|---|---|---|
index |
Int! |
no | Position, from 0. |
src |
String! |
no | Image URL. |
width |
Int! |
no | Width in pixels. |
height |
Int! |
no | Height in pixels. |
GemCertificate
Object. A gemstone grading certificate. The grading fields are optional: not every authority reports every one. Used by gemCertificate.
| Field | Type | Null | Description |
|---|---|---|---|
productId |
ID! |
no | The product. |
certificateNumber |
String! |
no | Certificate number. |
issuingAuthority |
GemCertAuthority! |
no | Who issued it. |
issuedAt |
String! |
no | Issue date (ISO 8601, e.g. 2026-04-12). |
reportUrl |
String |
yes | The report on the authority's site, for buyers to verify. |
shape |
String |
yes | Shape. |
caratWeight |
Float |
yes | Carat weight. |
color |
String |
yes | Colour grade. |
clarity |
String |
yes | Clarity grade. |
cut |
String |
yes | Cut grade. |
polish |
String |
yes | Polish grade. |
symmetry |
String |
yes | Symmetry grade. |
fluorescence |
String |
yes | Fluorescence. |
measurements |
String |
yes | Measurements, e.g. 5.20 x 5.22 x 3.18 mm. |
comments |
String |
yes | Comments. |
imageUrl |
String |
yes | Image of the certificate. |
GemCertAuthority
Enum. A gem grading authority. Used by gemCertificate.
| Value | Meaning |
|---|---|
GIA |
Gemological Institute of America. |
IGI |
International Gemological Institute. |
AGS |
American Gem Society. |
HRD |
HRD Antwerp. |
GCAL |
Gem Certification & Assurance Lab. |
OTHER |
Another authority. |
CustomerProfile
Object. The signed-in shopper. Used by customerMe.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
email |
String |
yes | Email. |
phone |
String |
yes | Phone. |
firstName |
String |
yes | First name. |
lastName |
String |
yes | Last name. |
gender |
String |
yes | Gender, as entered. |
dob |
String |
yes | Date of birth. |
marketingEmailOptIn |
Boolean! |
no | Agreed to marketing email. |
marketingSmsOptIn |
Boolean! |
no | Agreed to marketing SMS. |
marketingWhatsappOptIn |
Boolean! |
no | Agreed to marketing WhatsApp. |
emailVerifiedAt |
String |
yes | When the email was verified (ISO timestamp); null when not. |
phoneVerifiedAt |
String |
yes | When the phone was verified; null when not. |
lastLoginAt |
String |
yes | Last sign-in. |
createdAt |
String! |
no | Account creation. |
softDeletedAt |
String |
yes | When the shopper deleted the account; null otherwise. |
CustomerOrderList
Object. A page of the shopper's orders. Used by customerOrders.
| Field | Type | Null | Description |
|---|---|---|---|
orders |
[CustomerOrder!]! |
no | Orders of this page. |
total |
Int! |
no | Orders over all pages. |
page |
Int! |
no | This page (from 1). |
totalPages |
Int! |
no | Number of pages. |
CustomerOrder
Object. One order of the shopper. Amounts are in currency. Used by customerOrders, customerOrderDetail.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
orderNumber |
String! |
no | Order number to show. |
status |
String! |
no | Order status. |
paymentStatus |
String! |
no | Payment status. |
subtotal |
Float! |
no | Items total. |
tax |
Float! |
no | Tax. |
shippingCost |
Float! |
no | Shipping. |
discount |
Float! |
no | Discount. |
total |
Float! |
no | Amount paid. |
currency |
String! |
no | ISO 4217 code. |
shippingName |
String! |
no | Recipient. |
shippingAddress |
String! |
no | Street address. |
shippingCity |
String! |
no | City. |
shippingState |
String! |
no | State. |
shippingCountry |
String! |
no | Country. |
shippingPincode |
String! |
no | Postal code. |
shippingMethod |
String |
yes | Shipping method. |
customerNote |
String |
yes | The shopper's note. |
couponCode |
String |
yes | Coupon used. |
createdAt |
String! |
no | When it was placed. |
items |
[CustomerOrderItem!]! |
no | Order lines. |
shipment |
CustomerShipment |
yes | Shipment tracking; null before it ships. |
canReturn |
Boolean! |
no | A return can be requested now. |
canReorder |
Boolean! |
no | It can be ordered again. |
CustomerOrderItem
Object. One order line. Used by customerOrders, customerOrderDetail.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
productId |
String! |
no | The product. |
productName |
String! |
no | Product name at order time. |
productSlug |
String |
yes | Product handle, for a link; null when the product is gone. |
quantity |
Int! |
no | Quantity. |
unitPrice |
Float! |
no | Price per unit. |
totalPrice |
Float! |
no | Line total. |
colorName |
String |
yes | Colour chosen. |
sizeName |
String |
yes | Size chosen. |
image |
String |
yes | Image URL. |
CustomerShipment
Object. Shipment tracking. Used by customerOrders, customerOrderDetail.
| Field | Type | Null | Description |
|---|---|---|---|
trackingNumber |
String |
yes | Tracking number. |
trackingUrl |
String |
yes | Tracking page. |
carrier |
String |
yes | Carrier. |
status |
String |
yes | Shipment status. |
estimatedDelivery |
String |
yes | Estimated delivery date. |
CustomerAddressList
Object. The shopper's saved addresses. Used by customerSavedAddresses.
| Field | Type | Null | Description |
|---|---|---|---|
addresses |
[CustomerAddress!]! |
no | The addresses. |
CustomerAddress
Object. A saved address. Used by customerSavedAddresses.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
label |
String |
yes | Label, e.g. Home. |
firstName |
String! |
no | First name. |
lastName |
String! |
no | Last name. |
line1 |
String! |
no | Address line 1. |
line2 |
String |
yes | Address line 2. |
city |
String! |
no | City. |
state |
String! |
no | State. |
country |
String! |
no | Country. |
pincode |
String! |
no | Postal code. |
phone |
String |
yes | Phone. |
isDefault |
Boolean! |
no | The default address. |
CustomerWishlistResult
Object. The shopper's wishlist. Used by customerWishlist.
| Field | Type | Null | Description |
|---|---|---|---|
items |
[CustomerWishlistItem!]! |
no | Wishlist entries. |
CustomerWishlistItem
Object. One wishlist entry. Used by customerWishlist.
| Field | Type | Null | Description |
|---|---|---|---|
productId |
String! |
no | The product. |
addedAt |
String! |
no | When it was added. |
product |
WishlistProduct |
yes | The product; null when it is no longer for sale. |
WishlistProduct
Object. A product on a wishlist. Used by customerWishlist.
| Field | Type | Null | Description |
|---|---|---|---|
id |
ID! |
no | Stable id. |
handle |
String! |
no | URL name. |
title |
String! |
no | Product name. |
price |
Money! |
no | Price. |
image |
Image |
yes | Primary image. |
inStock |
Boolean! |
no | Can be bought now. |
Rules for gql()
Which documents are allowed.
- There is no document safelist on the paths a theme's
gql()takes. The page endpoint runs the document in-process against/graphql/storefront, and a runtime block's renderer posts it there, as written. The persisted-query table (apps/storefront-v2/src/lib/clients/persisted-queries.ts,PERSISTED_QUERIES) is the storefront host's own client table, and the safelist of marketplace themes rendered in the sandboxed tier, which can only name an entry of it (apps/storefront-v2/src/lib/theme-render/capability.ts). The gateway's safelist mode is off (docs/ops/cosmo/router-config.yaml). - Every document passes the storefront query limits (
apps/backend/crates/bp-graphql/src/plugins/query_protection.rs): depth at most 10, cost at most 5000, at most 15 aliases, and at most 50 of root-field cost (the "Root cost" column above; other fields cost 1). A page size written as a literal (limit,first,pageSize,productLimit,take) multiplies the cost of everything under it, a variable does not: pass sizes as variables. - With a developer token, only queries whose root fields are all in
DEV_TOKEN_OPS(apps/backend/crates/bp-graphql/src/dev_token.rs): no mutation, no fragment at the root, and everystoreSlugmust be the token's store. - Write a single query with one root field. Queries only: a document with a
mutationorsubscriptionanywhere in it (even next to a query), one the reader cannot parse, or one that is not a fixed string failsbizzpocket buildwithGQL_NOT_A_QUERY, and is refused at runtime without a request (the need resolves tonull; the page is not marked degraded) by the renderer (packages/theme-runtime/src/operations.ts,isQueryDocumentfrompackages/theme/src/gql-doc.ts) and by the page endpoint (apps/backend/crates/bp-svc-storefront-page/src/kinds.rs,gql_query_only). The schema also has root fields the SDK does not wrap (layoutFor,storeSitemap,catalogEntity,merchantFeed,storeSeo,storeTheme): host plumbing for layouts, themes, SEO, sitemaps and feeds, not documented here and not allowed with a developer token. Its mutations (cartAdd,cartUpdate,cartRemove,cartClear,customerUpdate,wishlistAdd,wishlistRemove,addressCreate,addressUpdate,addressDelete) are for the storefront host's cart and account routes. - Production does not answer introspection: this page is the schema.
How variables bind.
- The second argument of
gql()is the variables object. In a staticdata(), any value in it may be a prop or a route value passed straight through, at any depth:gql(DOC, { handle: route.handle, n: count, f: { handles: picks } }). The build records them as$prop/$routereferences; the server substitutes the saved prop (read likereadPropsreads it, else the field default) or the route value (pageType,handle,q,page,sort,filters), elsenull. - Top-level
nullvariables are dropped before sending, so anullfor a non-null variable ($handle: String!) is a GraphQL error: the need resolves tonulland the page is marked degraded.gql()only requiresdocument; check your required variables yourself. - Nobody fills
storeSlugfor you ingql()(except a developer token, which fills it with its store), anddata()cannot read the store slug. ForstoreProfile,storeHomeandcategoryFilters, usestore(),home()orctx.query. - The result is the value of the single root field:
gql<{ categories: Category[] }>('query Top($depth: Int!) { categoryTree(depth: $depth) { categories { id title href } } }', { depth: 1 })gives{ categories: [...] }, not{ categoryTree: ... }. With several root fields you get the wholedataobject. TypeTyourself: nothing checks the document against the schema at build time. - In a runtime block, identical (document, variables) pairs run once per page; in a static block, identical needs across the page run once.
Known differences
Mismatches between the TypeScript types and helper signatures in @bizzpocket/theme, the SDK's documents, the Rust backend and the guides, as of this page's generation. The page above follows the schema (what really arrives). Computed:
- None.
Found by hand:
- None.