BizzPocket

GraphQL reference

On this page

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 null or undefined is skipped and resolves to null (no request).
  • Each operation has 3 s. A failure, a GraphQL error or a timeout gives null and marks the page degraded.
  • Identical needs (same operation, same variables) run once per page, even across blocks.
  • The result your render receives is the operation's top-level field (data.productGridProducts), or null.

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
  • limit is clamped to 1..100; page starts at 1 (anything lower reads as 1).
  • collectionSlug is 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.
  • facets and priceRange are only computed when the document selects them.
  • In filters, a non-empty size replaces color (only one of the two applies). handles wins over featured.

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

graphql
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 storeSlug with 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

graphql
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 storeSlug with 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

graphql
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
  • depth is clamped to 1..5.
  • The SDK document selects three levels (categories, their children, and theirs). A deeper tree needs your own gql() document.

Variables

Variable Type Required Argument Schema default Filled from
$depth Int! yes depth 2 categories({ depth })

Document

graphql
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
  • main and footer always answer: when the seller has not saved them they are generated from the categories and policies (generated: true). Any other handle is null until 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

graphql
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
  • null when no active product has the handle.
  • reviews holds 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

graphql
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
  • limit is 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

graphql
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
  • limit defaults to 20 and is clamped to 1..100; page starts 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

graphql
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
  • featuredCount is 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

graphql
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 storeSlug with 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

graphql
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
  • limit defaults 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

graphql
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
  • frameCount is 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

graphql
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
  • null when the product has none.

Variables

Variable Type Required Argument Schema default Filled from
$productId ID! yes productId

Document

graphql
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
  • null when nobody is signed in. Shopper data: load() only.

Variables: none.

Document

graphql
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
  • limit defaults to 10 and is clamped to 1..50; page starts 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

graphql
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
  • null when the order is not theirs or nobody is signed in.

Variables

Variable Type Required Argument Schema default Filled from
$orderId ID! yes orderId

Document

graphql
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

graphql
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

graphql
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.

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.

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).

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.

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.

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.

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 every storeSlug must be the token's store.
  • Write a single query with one root field. Queries only: a document with a mutation or subscription anywhere in it (even next to a query), one the reader cannot parse, or one that is not a fixed string fails bizzpocket build with GQL_NOT_A_QUERY, and is refused at runtime without a request (the need resolves to null; the page is not marked degraded) by the renderer (packages/theme-runtime/src/operations.ts, isQueryDocument from packages/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 static data(), 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 / $route references; the server substitutes the saved prop (read like readProps reads it, else the field default) or the route value (pageType, handle, q, page, sort, filters), else null.
  • Top-level null variables are dropped before sending, so a null for a non-null variable ($handle: String!) is a GraphQL error: the need resolves to null and the page is marked degraded. gql() only requires document; check your required variables yourself.
  • Nobody fills storeSlug for you in gql() (except a developer token, which fills it with its store), and data() cannot read the store slug. For storeProfile, storeHome and categoryFilters, use store(), home() or ctx.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 whole data object. Type T yourself: 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.