Read Products and Categories with the Core Subgraph.

Queries

Get Product by ID, SKU, or slug

QUERYproduct
Pass exactly one of id, sku, or slug, otherwise the query returns a BAD_USER_INPUT error. Null when no Product in the Store's assortment matches.
Works without Product Search. To get several Products by ID, send one aliased product(id:) field per ID.
Arguments
id​
ID​

Unique identifier of the Product.

sku​
String​

SKU of one of the Product's variants.

slug​
String​

Slug of the Product for the session's locale.

Output:Product
Request Example:graphql
query GetProduct {
  product(slug: "oak-dining-chair") {
    id
    slug
    productName
    description
    price { formatted }
    availability { inStock quantity }
    variants { sku }
  }
}
Response Example:json
{
  "data": {
    "product": {
      "id": "AQAAAREQERAREUEQoRAREREQERAAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "slug": "oak-dining-chair",
      "productName": "Oak Dining Chair",
      "description": "A solid oak dining chair with a curved backrest.",
      "price": { "formatted": "£89.00" },
      "availability": { "inStock": true, "quantity": 3 },
      "variants": [{ "sku": "CHAIR-OAK-01" }, { "sku": "CHAIR-OAK-02" }]
    }
  }
}

Query Products

QUERYproducts
Lists the Products in the Store's assortment, without a search text or facets. Use search for text search and a filter rail.
Requires Product Search to be enabled for the Project, otherwise the query returns a PRODUCT_SEARCH_NOT_ENABLED error. Catalog changes appear with a short delay.
Arguments
filter​

Filters to apply to the list.

sort​

Sort order of the list.

first​
Int​
Number of Products to return, from 0 to 100. A value outside this range returns a BAD_USER_INPUT error whose extensions name the argument and the limit.
Default: 20​
after​
String​
Cursor after which the page starts, from ProductEdge.cursor or PageInfo.endCursor. A cursor that this API didn't issue returns a BAD_USER_INPUT error.
Request Example:graphql
query ListProducts {
  products(sort: {field: NAME}, first: 2) {
    totalCount
    pageInfo { hasNextPage endCursor }
    nodes { slug productName }
  }
}
Response Example:json
{
  "data": {
    "products": {
      "totalCount": 48,
      "pageInfo": { "hasNextPage": true, "endCursor": "AW9nZ3NkdDsx" },
      "nodes": [
        { "slug": "linen-cushion", "productName": "Linen Cushion" },
        {
          "slug": "oak-dining-chair",
          "productName": "Oak Dining Chair"
        }
      ]
    }
  }
}

Search Products

QUERYsearch

Searches the Products in the Store's assortment by text and returns a page of results with facets for a filter rail.

Requires Product Search to be enabled for the Project, otherwise the query returns a PRODUCT_SEARCH_NOT_ENABLED error.
Arguments
query​
String​

Text to search for in the Product name, description, slug, and search keywords for the session's locale.

queryMode​
Matching mode for query. Defaults to FULL_TEXT.
Can be FULL_TEXT, CONTAINS, FUZZY, or PREFIX​
filter​

Filters to apply to the result.

sort​

Sort order of the result.

first​
Int​
Number of Products to return, from 0 to 100. A value outside this range returns a BAD_USER_INPUT error whose extensions name the argument and the limit.
Default: 20​
after​
String​
Cursor after which the page starts, from ProductEdge.cursor or PageInfo.endCursor. A cursor that this API didn't issue returns a BAD_USER_INPUT error.
Request Example:graphql
query SearchProducts {
  search(query: "chair", filter: {priceMax: 100}, sort: {field: PRICE}, first: 20) {
    totalCount
    facets {
      label
      options { value count }
    }
    nodes { productName }
  }
}
Response Example:json
{
  "data": {
    "search": {
      "totalCount": 1,
      "facets": [
        {
          "label": "Finish",
          "options": [
            { "value": "natural-oak", "count": 1 },
            { "value": "smoked-oak", "count": 1 }
          ]
        }
      ],
      "nodes": [{ "productName": "Oak Dining Chair" }]
    }
  }
}

Query Categories

QUERYcategories
Flat list of up to 500 Categories of the Project, root Categories and their descendants together, in ascending orderHint order. Use parent and children to build the tree.
Output:Category
Request Example:graphql
query GetCategories {
  categories {
    slug
    name
    parent { slug }
  }
}
Response Example:json
{
  "data": {
    "categories": [
      { "slug": "furniture", "name": "Furniture", "parent": null },
      {
        "slug": "dining-chairs",
        "name": "Dining Chairs",
        "parent": { "slug": "furniture" }
      }
    ]
  }
}

Get Category by ID or slug

QUERYcategory
Pass exactly one of id or slug, otherwise the query returns a BAD_USER_INPUT error. Null when no Category matches.
Arguments
id​
ID​

Unique identifier of the Category.

slug​
String​

Slug of the Category for the session's locale.

Output:Category
Request Example:graphql
query GetCategory {
  category(slug: "dining-chairs") {
    id
    slug
    name
    description
    parent { slug name }
    children { slug }
  }
}
Response Example:json
{
  "data": {
    "category": {
      "id": "AQUAAWZnZmdmZkZnpmdmZmZnZmcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "slug": "dining-chairs",
      "name": "Dining Chairs",
      "description": "Chairs for the dining room and kitchen.",
      "parent": { "slug": "furniture", "name": "Furniture" },
      "children": []
    }
  }
}

Output types

Product

A Product in the Store's assortment.

Each Project adds an attributes field to Product and ProductVariant, generated from its Product Types. It returns the ProductAttributes or ProductVariantAttributes interface, with one implementing <ProductType>Attributes type per Product Type, and a raw JSON map of the attribute values.
id​
ID​

Unique identifier of the Product.

key​
String​

User-defined unique identifier of the Product.

slug​
String​

User-defined identifier used in a deep-link URL for the Product, for the session's locale.

productName​
String​

Name of the Product, for the session's locale.

description​
String​

Description of the Product, for the session's locale. Null when the Product has no description.

categories​
Array of Category​

Categories assigned to the Product.

images​
Array of Image​

Images of the default variant.

price​
Price of the default variant, resolved as described on ProductVariant.price.
null when the session isn't entitled to a price, or the default variant has no price in the session's currency or country. addCartLine refuses such a variant with PRICE_NOT_AVAILABLE. Other variants can still have a price, so check variants.
priceBeforeDiscount​

The price before its Product Discount: the strike-through price.

discountedPrice​
The default variant's price after its Product Discount, and the Product Discount behind it; null when no Product Discount applies. price then equals discountedPrice.value.
availability​
Inventory of the default variant, counted as described on ProductVariant.availability.
options​
Array of ProductOption​

Axes on which the Product's variants differ, for rendering a variant picker. Empty when the variants don't differ on any selectable attribute.

variants​
Array of ProductVariant​

Variants of the Product, starting with the default variant. Variants without a SKU are left out.

defaultVariant​

Default variant of the Product. This is the master variant, or the first variant with a SKU when the master variant has none.

matchingVariants​
Array of ProductVariant​
Variants that matched the query or filter of Query.search or Query.products. Null when the Product was read another way.
attributeLabels​
Array of AttributeLabel​

Labels for the Product's attributes. Use them to label attribute rows without selecting a specific Product Type.

_standalonePrices​
All Standalone Prices of the Product's variants, for extensions. Storefronts read ProductVariant.price. Not part of the public API: an extension can read it with @requires, and it's removed from the composed API schema.
_ctId​
ID​
Platform identifier (UUID) of the Product, for extensions that key an external system by it. The public id is an opaque global identifier, so don't parse it. Not part of the public API: an extension can read it with @requires, and it's removed from the composed API schema.

InternalStandalonePrice

One Standalone Price of a Product Variant, as returned to extensions by Product._standalonePrices.
sku​
String​

SKU of the Product Variant the price applies to.

channelId​
ID​

Identifier of the distribution Channel the price is scoped to. Null when the price has no Channel.

channelKey​
String​

Key of the distribution Channel the price is scoped to. Null when the price has no Channel or the Channel has no key.

centAmount​
Int​

Amount in the smallest indivisible unit of the currency, such as cents for EUR and USD, or pence for GBP.

currencyCode​
String​

Currency code compliant to ISO 4217.

Product Variant

A purchasable version of a Product, such as one combination of size and color.

id​
ID​

Unique identifier of the Product Variant. Unique across all Products.

sku​
String​
SKU of the Product Variant. Unique across all Product Variants in a Project. Pass it to addCartLine to add the variant to the Cart.
selectedOptions​
Array of SelectedOption​
Values of this variant on the axes in Product.options. Axes for which the variant has no value are left out.
price​

Price of the variant for the session's currency, country, distribution channel, and Customer Group, with any Product Discount applied.

null if the session isn't entitled to a price, if the variant has no price for the session's currency or country, or if the Store has no prices in the session's currency. Adding such a variant with addCartLine returns PRICE_NOT_AVAILABLE.
priceBeforeDiscount​

The price before its Product Discount: the strike-through price.

discountedPrice​
The price after its Product Discount, and the Product Discount behind it; null when no Product Discount applies. price then equals discountedPrice.value.
priceTiers​
Array of PriceTier​
Price tiers of price, lowest minimumQuantity first. Empty when the price has no tiers or the variant has no price.
availability​

Inventory of the variant for the session's supply channel. Without a supply channel, the stock of all supply channels is added up.

images​
Array of Image​

Images of the Product Variant.

assets​
Array of Asset​
Assets of the Product Variant, such as documents, videos, or 3D models. Empty when the variant has no Assets, or none matches tags.

Discounted Price

A product's price after its Product Discount, per unit.

value​
productDiscount​

Asset

Digital asset of a Product Variant, such as a document, a video, or a 3D model, with its files in sources. Text fields are resolved for the session's locale.
key​
String​

User-defined identifier of the Asset. Unique within the Product Variant.

name​
String​

Name of the Asset, for the session's locale. An empty string when the Asset has no name.

description​
String​

Description of the Asset, for the session's locale. Null when the Asset has no description.

tags​
Array of String​

Keywords for categorizing and organizing Assets. Empty when the Asset has no tags.

sources​
Array of AssetSource​

Files of the Asset. One Asset can have several, for example the same video in different formats or resolutions.

Example:json
{
  "key": "assembly-instructions",
  "name": "Assembly instructions",
  "description": "Step-by-step guide for assembling the chair.",
  "tags": ["manual"],
  "sources": [
    {
      "uri": "https://assets.example.com/oak-dining-chair-assembly.pdf",
      "key": "pdf",
      "contentType": "application/pdf",
      "width": null,
      "height": null
    }
  ]
}

Asset Source

One file of an Asset.

uri​
String​

URI of the file.

key​
String​

User-defined identifier of the source. Unique within the Asset.

contentType​
String​
Media type of the file, for example application/pdf. Null if not set.
width​
Int​

Width of the file. Null if not set.

height​
Int​

Height of the file. Null if not set.

Example:json
{
  "uri": "https://assets.example.com/oak-dining-chair-360.mp4",
  "key": "video-1080p",
  "contentType": "video/mp4",
  "width": 1920,
  "height": 1080
}

Selected Option

One variant's value on a ProductOption axis.
code​
String​
Name of the attribute, matching ProductOption.code.
value​
String​
Value of the variant for the attribute, in the same form as ProductOptionValue.value, for example #FFF.

Price Tier

A volume price of a Product Variant. From minimumQuantity units on a Cart line, each unit costs price.
minimumQuantity​
Int​
Minimum quantity this price tier is valid for. Always 2 or greater, since a single unit costs the variant's price.
price​

Price of one unit at this quantity, not the line total.

Product Option

A variant selection axis of a Product, such as color or size.

An axis is a variant-level attribute of type text, localized text, enum, localized enum, number, or boolean whose value differs across the Product's variants. A Product with one variant has no axes. When several attributes vary, each one is reported as its own axis, so choose the code values you want to render.
code​
String​

Name of the attribute behind this axis.

label​
String​
Display label of the attribute for the session's locale. Falls back to code when the attribute definition has no label for that locale.
values​
Array of ProductOptionValue​

Distinct values of the attribute across the Product's variants, in the order in which the variants first use them.

Product Option Value

A value a shopper can pick on a ProductOption axis. A variant has this value when its SelectedOption with the same code has the same value.
value​
String​

Attribute value as stored, such as an enum key, or localized text resolved for the session's locale.

label​
String​
Display label of the value for the session's locale. Falls back to value when the value has no label.

Attribute Label

An attribute name paired with its display label.

name​
String​
Name of the attribute, for example iso45001.
label​
String​
Display label of the attribute for the session's locale, for example ISO 45001. Falls back to name when the attribute definition has no label for that locale.

Category

A Category of the Project, used to group Products for navigation. Pass its slug as ProductFilter.categorySlug to list its Products. Text fields are resolved for the session's locale.
id​
ID​

Unique identifier of the Category.

key​
String​

User-defined unique identifier of the Category.

slug​
String​

User-defined identifier used as a deep-link URL to the Category, for the session's locale. An empty string when the Category has no slug for that locale.

name​
String​

Name of the Category, for the session's locale. An empty string when the Category has no name for that locale.

description​
String​

Description of the Category, for the session's locale. Null when the Category has no description for that locale.

orderHint​
String​

Decimal value between 0 and 1 for ordering Categories within the same level of the category tree.

parent​

Parent Category of this Category. Null for a root Category.

children​
Array of Category​
Child Categories of this Category, sorted by orderHint in ascending order. Empty for a Category without children.
_ctId​
ID​
Platform identifier (UUID) of the Category, for extensions that correlate a search index or merchandising system by it. The public id is an opaque global identifier, so don't parse it.
Not part of the public API: an extension can read it with @requires, and it is removed from the composed API schema.

Product Connection

A page of Products returned by Query.products.
edges​
Array of ProductEdge​

Products on this page, with their cursors.

nodes​
Array of Product​
Products on this page, in the same order as edges.
pageInfo​

Pagination information for this page.

totalCount​
Int​

Total number of Products that match the request, across all pages.

Product Edge

Edge of a ProductConnection or ProductSearchConnection.
node​

Product at this position in the list.

cursor​
String​
Opaque cursor of this Product. Pass it as after to get the Products that follow it.

Product Search Connection

A page of Query.search results. Same as ProductConnection, plus facets.
facets​
Array of Facet​

Facets of the search result.

edges​
Array of ProductEdge​

Products on this page, with their cursors.

nodes​
Array of Product​
Products on this page, in the same order as edges.
pageInfo​

Pagination information for this page.

totalCount​
Int​

Total number of Products that match the search, across all pages.

Facet

Filter-rail entry for one attribute of the search result.

Facets are built from the Project's searchable attributes of type enum, localized enum, boolean, and number. To filter on a value that options doesn't list, pass it in ProductFilter.attributes.
code​
String​
Identifier of the attribute, in the format variants.attributes.<attributeName>. Pass it unchanged as code in AttributeFilterInput or AttributeRangeFilterInput.
label​
String​

Display label of the attribute for the session's locale. Falls back to the attribute name.

options​
Array of FacetOption​
Up to 10 most common values, highest count first. Values with the same count are sorted by value, so the order is stable between requests.

Facet Option

A selectable entry of a Facet.
value​
String​
Attribute value as stored, such as an enum key. Pass it in AttributeFilterInput.values to filter on it.
label​
String​
Display label of the value for the session's locale. Falls back to value when the value has no label.
count​
Int​

Number of Products in the result that have this value.

Attribute Filter Operator

How the values of an AttributeFilterInput are matched against the attribute.
EXACT
Matches a value exactly.
FUZZY
Matches a value with small typos. The tolerance increases with the length of the value.
PREFIX
Matches an attribute value that starts with the given text.
WILDCARD
Matches using the `*` and `?` wildcards written in the value.
EXISTS
Matches Products that have any value for the attribute.

Product Sort Field

Sort key of ProductSort. Each value has its own default direction.
RELEVANCE
Relevance to the search `query`. Most relevant first by default.
PRICE
Price for the session. Cheapest first by default, and `direction: DESC` reverses it. Ascending order uses each Product's cheapest variant price, and descending order its most expensive one. This can differ from `Product.price`, which is the price of the DEFAULT variant, so a Product's position may not match the price it shows. To show the prices a Product was ranked on, select `variants { price }`. `ProductFilter.priceMin` and `ProductFilter.priceMax` use the same per-variant rule.
NAME
Product name for the session's locale. A to Z by default.
NEWEST
Creation date of the Product. Newest first by default.

Search Query Mode

Text matching mode of Query.search. A query equal to a variant's SKU matches that Product in every mode.
FULL_TEXT
Matches whole words: every word of `query` must appear in the field, in any order. A fragment of a word does not match, so `bat` does not find `battery`. This is the default.
CONTAINS
Matches when the text appears anywhere in the field, including inside a word (`bat` finds `battery`), ignoring case.
FUZZY
Matches with small typos. The tolerance increases with the length of `query`.
PREFIX
Matches when the field starts with the text, ignoring case.

Input types

Product Filter

Conditions on a Product list or search. Each field you set narrows the result further. A categorySlug that matches no Category, or an attribute code the Project can't filter on, returns an empty page.
categorySlug​
String​

Slug of a Category for the session's locale. Returns only Products assigned to that Category.

onSale​
Boolean​
Whether to return only Products with a discounted price for the session (true), or only Products without one (false). Decided per variant, like priceMin: true can return a Product whose Product.price isn't discounted, and false can return a Product that has a discounted variant.
priceMin​
Float​
Lowest price to include, in major units of the session's currency, for example 50 for £50.00. Discounted prices are compared per variant, as described on ProductSortField.PRICE, so a Product can match while Product.price is outside the range.
priceMax​
Float​
Highest price to include, in major units of the session's currency. Compared like priceMin.
attributes​
Filters on the Product's attributes. Accepts any value of the attribute, including values that Facet.options doesn't list.

Also accepts the Project's searchable text attributes, which have no facet. A localized text attribute is matched on its value for the session's locale.

attributeRanges​
Numeric range filters on the Product's attributes, by the same code as attributes.

Attribute Filter Input

Condition on one searchable attribute. Several entries in ProductFilter.attributes must all match.
code​
String​
Identifier of the attribute, as reported in Facet.code, for example variants.attributes.finish.
Matching mode for values. Defaults to EXACT.
Can be EXACT, FUZZY, PREFIX, WILDCARD, or EXISTS​
values​
Array of String​
Values to match. A Product matches when it has any of them. An empty list applies no filter. Ignored when operator is EXISTS.

Attribute Range Filter Input

Numeric counterpart of AttributeFilterInput.
code​
String​
Identifier of the attribute, as reported in Facet.code.
min​
Float​

Lowest value to include.

max​
Float​

Highest value to include.

Product Sort

Sort order for Query.products and Query.search.
Omitting sort, passing sort: {}, and passing sort: {field: RELEVANCE} return the same order. Products that sort equally are always returned in the same order, so paging doesn't repeat or skip a Product.
field​
Field to sort by. Defaults to RELEVANCE.
Can be RELEVANCE, PRICE, NAME, or NEWEST​Default: RELEVANCE​
direction​
Direction of the sort. Omit it to use the default direction of field, listed on each ProductSortField value. Set it only to reverse that default.
Can be ASC, or DESC​