Storefront API

Use the storefront GraphQL API to access rich view-model (read-only) catalog data to build product-related storefront experiences. For more information about the API, see the developer documentation.

API Endpoints
https://<your store>/graphql
Headers
# Your API token from the dashboard. Must be included in all API calls.
Authorization: Bearer <YOUR_TOKEN_HERE>

Queries

attributeMetadata

Description

Return a list of product attribute codes that can be used for sorting or filtering in a productSearch query

Response

Returns an AttributeMetadataResponse!

Example

Query
query attributeMetadata {
  attributeMetadata {
    filterableInSearch {
      ...FilterableInSearchAttributeFragment
    }
    sortable {
      ...SortableAttributeFragment
    }
  }
}
Response
{
  "data": {
    "attributeMetadata": {
      "filterableInSearch": [FilterableInSearchAttribute],
      "sortable": [SortableAttribute]
    }
  }
}
back to top
Queries

productSearch

Description

Search products using Live Search

Response

Returns a ProductSearchResponse!

Arguments
Name Description
context - QueryContextInput The query context
current_page - Int Specifies which page of results to return. The default value is 1. Default = 1
filter - [SearchClauseInput!] Identifies product attributes and conditions to filter on
page_size - Int The maximum number of results to return at once. Default = 20
phrase - String! Phrase to search for in product catalog
sort - [ProductSearchSortInput!] Attributes and direction to sort on

Example

Query
query productSearch(
  $context: QueryContextInput,
  $current_page: Int,
  $filter: [SearchClauseInput!],
  $page_size: Int,
  $phrase: String!,
  $sort: [ProductSearchSortInput!]
) {
  productSearch(
    context: $context,
    current_page: $current_page,
    filter: $filter,
    page_size: $page_size,
    phrase: $phrase,
    sort: $sort
  ) {
    facets {
      ...AggregationFragment
    }
    items {
      ...ProductSearchItemFragment
    }
    page_info {
      ...SearchResultPageInfoFragment
    }
    related_terms
    suggestions
    total_count
  }
}
Variables
{
  "context": QueryContextInput,
  "current_page": 1,
  "filter": [SearchClauseInput],
  "page_size": 20,
  "phrase": "xyz789",
  "sort": [ProductSearchSortInput]
}
Response
{
  "data": {
    "productSearch": {
      "facets": [Aggregation],
      "items": [ProductSearchItem],
      "page_info": SearchResultPageInfo,
      "related_terms": ["abc123"],
      "suggestions": ["xyz789"],
      "total_count": 987
    }
  }
}
back to top
Queries

products

Description

Search for products that match the specified SKU values.

Response

Returns [ProductView]

Arguments
Name Description
skus - [String]

Example

Query
query products($skus: [String]) {
  products(skus: $skus) {
    addToCartAllowed
    inStock
    lowStock
    attributes {
      ...ProductViewAttributeFragment
    }
    description
    id
    images {
      ...ProductViewImageFragment
    }
    videos {
      ...ProductViewVideoFragment
    }
    lastModifiedAt
    metaDescription
    metaKeyword
    metaTitle
    name
    shortDescription
    inputOptions {
      ...ProductViewInputOptionFragment
    }
    sku
    externalId
    url
    urlKey
    links {
      ...ProductViewLinkFragment
    }
    categories
    queryType
    rank
    score
    visibility
  }
}
Variables
{"skus": ["xyz789"]}
Response
{
  "data": {
    "products": [
      {
        "addToCartAllowed": false,
        "inStock": true,
        "lowStock": true,
        "attributes": [ProductViewAttribute],
        "description": "xyz789",
        "id": 4,
        "images": [ProductViewImage],
        "videos": [ProductViewVideo],
        "lastModifiedAt": "2007-12-03T10:15:30Z",
        "metaDescription": "abc123",
        "metaKeyword": "abc123",
        "metaTitle": "xyz789",
        "name": "abc123",
        "shortDescription": "xyz789",
        "inputOptions": [ProductViewInputOption],
        "sku": "abc123",
        "externalId": "abc123",
        "url": "xyz789",
        "urlKey": "abc123",
        "links": [ProductViewLink],
        "categories": ["abc123"],
        "queryType": "xyz789",
        "rank": 123,
        "score": 987.65,
        "visibility": "abc123"
      }
    ]
  }
}
back to top
Queries

recommendations

Description

Get Recommendations

Response

Returns a Recommendations

Arguments
Name Description
cartSkus - [String] SKUs of products in the cart
category - String Category currently being viewed
currentSku - String SKU of the product currently being viewed on PDP
pageType - PageType Type of page on which recommendations are requested
userPurchaseHistory - [PurchaseHistory] User purchase history with timestamp
userViewHistory - [ViewHistory] User view history with timestamp

Example

Query
query recommendations(
  $cartSkus: [String],
  $category: String,
  $currentSku: String,
  $pageType: PageType,
  $userPurchaseHistory: [PurchaseHistory],
  $userViewHistory: [ViewHistory]
) {
  recommendations(
    cartSkus: $cartSkus,
    category: $category,
    currentSku: $currentSku,
    pageType: $pageType,
    userPurchaseHistory: $userPurchaseHistory,
    userViewHistory: $userViewHistory
  ) {
    results {
      ...RecommendationUnitFragment
    }
    totalResults
  }
}
Variables
{
  "cartSkus": ["abc123"],
  "category": "xyz789",
  "currentSku": "xyz789",
  "pageType": "CMS",
  "userPurchaseHistory": [PurchaseHistory],
  "userViewHistory": [ViewHistory]
}
Response
{
  "data": {
    "recommendations": {
      "results": [RecommendationUnit],
      "totalResults": 987
    }
  }
}
back to top
Queries

refineProduct

Response

Returns a ProductView

Arguments
Name Description
optionIds - [String!]!
sku - String!

Example

Query
query refineProduct(
  $optionIds: [String!]!,
  $sku: String!
) {
  refineProduct(
    optionIds: $optionIds,
    sku: $sku
  ) {
    addToCartAllowed
    inStock
    lowStock
    attributes {
      ...ProductViewAttributeFragment
    }
    description
    id
    images {
      ...ProductViewImageFragment
    }
    videos {
      ...ProductViewVideoFragment
    }
    lastModifiedAt
    metaDescription
    metaKeyword
    metaTitle
    name
    shortDescription
    inputOptions {
      ...ProductViewInputOptionFragment
    }
    sku
    externalId
    url
    urlKey
    links {
      ...ProductViewLinkFragment
    }
    categories
    queryType
    rank
    score
    visibility
  }
}
Variables
{
  "optionIds": ["xyz789"],
  "sku": "abc123"
}
Response
{
  "data": {
    "refineProduct": {
      "addToCartAllowed": false,
      "inStock": false,
      "lowStock": true,
      "attributes": [ProductViewAttribute],
      "description": "xyz789",
      "id": "4",
      "images": [ProductViewImage],
      "videos": [ProductViewVideo],
      "lastModifiedAt": "2007-12-03T10:15:30Z",
      "metaDescription": "abc123",
      "metaKeyword": "xyz789",
      "metaTitle": "xyz789",
      "name": "xyz789",
      "shortDescription": "abc123",
      "inputOptions": [ProductViewInputOption],
      "sku": "abc123",
      "externalId": "abc123",
      "url": "xyz789",
      "urlKey": "xyz789",
      "links": [ProductViewLink],
      "categories": ["xyz789"],
      "queryType": "xyz789",
      "rank": 123,
      "score": 987.65,
      "visibility": "xyz789"
    }
  }
}
back to top
Queries

variants

Response

Returns a ProductViewVariantResults

Arguments
Name Description
sku - String!
optionIds - [String!]
pageSize - Int
cursor - String

Example

Query
query variants(
  $sku: String!,
  $optionIds: [String!],
  $pageSize: Int,
  $cursor: String
) {
  variants(
    sku: $sku,
    optionIds: $optionIds,
    pageSize: $pageSize,
    cursor: $cursor
  ) {
    variants {
      ...ProductViewVariantFragment
    }
    cursor
  }
}
Variables
{
  "sku": "abc123",
  "optionIds": ["xyz789"],
  "pageSize": 123,
  "cursor": "abc123"
}
Response
{
  "data": {
    "variants": {
      "variants": [ProductViewVariant],
      "cursor": "xyz789"
    }
  }
}
back to top

Types

Aggregation

Description

A bucket that contains information for each filterable option

Fields
Field Name Description
attribute - String! The attribute code of the filter item
buckets - [Bucket]! A container that divides the data into manageable groups. For example, attributes that can have numeric values might have buckets that define price ranges
title - String! The filter name displayed in layered navigation
type - AggregationType Identifies the data type of the aggregation
Example
{
  "attribute": "abc123",
  "buckets": [Bucket],
  "title": "xyz789",
  "type": "INTELLIGENT"
}
back to top
Types

AggregationType

Description

Identifies the data type of the aggregation

Values
Enum Value Description

INTELLIGENT

PINNED

POPULAR
Example
"INTELLIGENT"
back to top
Types

AppliedQueryRule

Description

The rule that was applied to this product

Fields
Field Name Description
action_type - AppliedQueryRuleActionType An enum that defines the type of rule that was applied
rule_id - String The ID assigned to the rule
rule_name - String The name of the applied rule
Example
{
  "action_type": "BOOST",
  "rule_id": "xyz789",
  "rule_name": "xyz789"
}
back to top
Types

AppliedQueryRuleActionType

Description

The type of rule that was applied to a product during search (optional)

Values
Enum Value Description

BOOST

BURY

PIN
Example
"BOOST"
back to top
Types

AttributeMetadataResponse

Description

Contains the output of the attributeMetadata query

Fields
Field Name Description
filterableInSearch - [FilterableInSearchAttribute!] An array of product attributes that can be used for filtering in a productSearch query
sortable - [SortableAttribute!] An array of product attributes that can be used for sorting in a productSearch query
Example
{
  "filterableInSearch": [FilterableInSearchAttribute],
  "sortable": [SortableAttribute]
}
back to top
Types

Boolean

Description

The Boolean scalar type represents true or false.

back to top
Types

Bucket

Description

An interface for bucket contents

Fields
Field Name Description
title - String! A human-readable name of a bucket
Possible Types
Bucket Types

CategoryView

RangeBucket

ScalarBucket

StatsBucket
Example
{"title": "abc123"}
back to top
Types

BundleProduct

Description

Defines features of a bundle product

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String Relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
weight - Float The weight of the item, in units defined by the store
Example
{
  "add_to_cart_allowed": true,
  "attribute_set_id": 987,
  "canonical_url": "xyz789",
  "created_at": "xyz789",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "xyz789",
  "id": 987,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "xyz789",
  "meta_title": "abc123",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "abc123",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "abc123",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": "4",
  "updated_at": "abc123",
  "weight": 123.45
}
back to top
Types

CategoryView

Description

Category view bucket for federation

Fields
Field Name Description
availableSortBy - [String]
children - [String!]
defaultSortBy - String
id - ID!
level - Int
name - String
parentId - String!
path - String
roles - [String!]!
urlKey - String
urlPath - String
count - Int!
title - String!
Example
{
  "availableSortBy": ["abc123"],
  "children": ["abc123"],
  "defaultSortBy": "abc123",
  "id": 4,
  "level": 123,
  "name": "xyz789",
  "parentId": "xyz789",
  "path": "abc123",
  "roles": ["abc123"],
  "urlKey": "abc123",
  "urlPath": "xyz789",
  "count": 123,
  "title": "xyz789"
}
back to top
Types

CategoryViewInterface

Fields
Field Name Description
availableSortBy - [String]
defaultSortBy - String
id - ID!
level - Int
name - String
path - String
roles - [String]
urlKey - String
urlPath - String
Possible Types
CategoryViewInterface Types

CategoryView
Example
{
  "availableSortBy": ["xyz789"],
  "defaultSortBy": "abc123",
  "id": "4",
  "level": 987,
  "name": "abc123",
  "path": "xyz789",
  "roles": ["xyz789"],
  "urlKey": "xyz789",
  "urlPath": "abc123"
}
back to top
Types

ComplexProductView

Description

Represents all product types, except simple products. Complex product prices are returned as a price range, because price values can vary based on selected options.

Fields
Field Name Description
addToCartAllowed - Boolean A flag stating if the product can be added to cart
inStock - Boolean A flag stating if the product is in stock
lowStock - Boolean A flag stating if the product stock is low
attributes - [ProductViewAttribute] A list of merchant-defined attributes designated for the storefront.
Arguments
roles - [String]
description - String The detailed description of the product.
id - ID! The product ID, generated as a composite key, unique per locale.
images - [ProductViewImage] A list of images defined for the product.
Arguments
roles - [String]
videos - [ProductViewVideo] A list of videos defined for the product.
lastModifiedAt - DateTime Date and time when the product was last updated.
metaDescription - String A brief overview of the product for search results listings.
metaKeyword - String A comma-separated list of keywords that are visible only to search engines.
metaTitle - String A string that is displayed in the title bar and tab of the browser and in search results lists.
name - String Product name.
inputOptions - [ProductViewInputOption] A list of input options.
options - [ProductViewOption] A list of selectable options.
priceRange - ProductViewPriceRange A range of possible prices for a complex product.
shortDescription - String A summary of the product.
sku - String Product SKU.
externalId - String External Id
url - String Canonical URL of the product.
urlKey - String The URL key of the product.
links - [ProductViewLink] A list of product links
Arguments
linkTypes - [String!]
categories - [String] List of categories to which the product belongs This field is deprecated and will be removed after Feb 1, 2024.
queryType - String Indicates if the product was retrieved from the primary or the backup query
rank - Int Rank given to a product This field is deprecated and will be removed after Feb 1, 2024.
score - Float Score indicating relevance of the product to the recommendation type This field is deprecated and will be removed after Feb 1, 2024.
visibility - String Visibility setting of the product
Example
{
  "addToCartAllowed": true,
  "inStock": false,
  "lowStock": true,
  "attributes": [ProductViewAttribute],
  "description": "abc123",
  "id": "4",
  "images": [ProductViewImage],
  "videos": [ProductViewVideo],
  "lastModifiedAt": "2007-12-03T10:15:30Z",
  "metaDescription": "xyz789",
  "metaKeyword": "xyz789",
  "metaTitle": "abc123",
  "name": "abc123",
  "inputOptions": [ProductViewInputOption],
  "options": [ProductViewOption],
  "priceRange": ProductViewPriceRange,
  "shortDescription": "abc123",
  "sku": "abc123",
  "externalId": "abc123",
  "url": "xyz789",
  "urlKey": "xyz789",
  "links": [ProductViewLink],
  "categories": ["xyz789"],
  "queryType": "abc123",
  "rank": 987,
  "score": 123.45,
  "visibility": "xyz789"
}
back to top
Types

ComplexTextValue

Description

Text that can contain HTML tags

Fields
Field Name Description
html - String! Text that can contain HTML tags
Example
{"html": "abc123"}
back to top
Types

ConfigurableProduct

Description

Basic features of a configurable product and its simple product variants

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String A relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
weight - Float The weight of the item, in units defined by the store
Example
{
  "add_to_cart_allowed": false,
  "attribute_set_id": 123,
  "canonical_url": "abc123",
  "created_at": "abc123",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "abc123",
  "id": 123,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "xyz789",
  "meta_title": "xyz789",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "xyz789",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "xyz789",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": "4",
  "updated_at": "xyz789",
  "weight": 987.65
}
back to top
Types

CurrencyEnum

Values
Enum Value Description

NONE

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

AWG

AZM

AZN

BAM

BBD

BDT

BGN

BHD

BIF

BMD

BND

BOB

BRL

BSD

BTN

BUK

BWP

BYN

BZD

CAD

CDF

CHE

CHF

CHW

CLP

CNY

COP

CRC

CUP

CVE

CZK

DJF

DKK

DOP

DZD

EEK

EGP

ERN

ETB

EUR

FJD

FKP

GBP

GEK

GEL

GHS

GIP

GMD

GNF

GQE

GTQ

GYD

HKD

HNL

HRK

HTG

HUF

IDR

ILS

INR

IQD

IRR

ISK

JMD

JOD

JPY

KES

KGS

KHR

KMF

KPW

KRW

KWD

KYD

KZT

LAK

LBP

LKR

LRD

LSL

LSM

LTL

LVL

LYD

MAD

MDL

MGA

MKD

MMK

MNT

MOP

MRO

MUR

MVR

MWK

MXN

MYR

MZN

NAD

NGN

NIC

NOK

NPR

NZD

OMR

PAB

PEN

PGK

PHP

PKR

PLN

PYG

QAR

RHD

ROL

RON

RSD

RUB

RWF

SAR

SBD

SCR

SDG

SEK

SGD

SHP

SKK

SLL

SOS

SRD

STD

SVC

SYP

SZL

THB

TJS

TMM

TND

TOP

TRL

TRY

TTD

TWD

TZS

UAH

UGX

USD

UYU

UZS

VEB

VEF

VND

VUV

WST

XCD

XOF

XPF

YER

ZAR

ZMK

ZWD
Example
"NONE"
back to top
Types

CustomAttribute

Description

A product attribute defined by the merchant

Fields
Field Name Description
code - String! The unique identifier for an attribute code
value - String! The value assigned to the custom attribute
Example
{
  "code": "abc123",
  "value": "abc123"
}
back to top
Types

DateTime

Description

An RFC-3339 compliant DateTime Scalar

Example
"2007-12-03T10:15:30Z"
back to top
Types

DownloadableProduct

Description

A product that the shopper downloads

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String A relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available.
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects.
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
Example
{
  "add_to_cart_allowed": false,
  "attribute_set_id": 123,
  "canonical_url": "xyz789",
  "created_at": "xyz789",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "abc123",
  "id": 987,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "xyz789",
  "meta_keyword": "abc123",
  "meta_title": "abc123",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "xyz789",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "xyz789",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": "4",
  "updated_at": "xyz789"
}
back to top
Types

FilterableInSearchAttribute

Description

Contains product attributes that can be used for filtering in a productSearch query

Fields
Field Name Description
attribute - String! The unique identifier for an attribute code. This value should be in lowercase letters and without spaces
frontendInput - String Indicates how field rendered on storefront
label - String The display name assigned to the attribute
numeric - Boolean Indicates whether this attribute has a numeric value, such as a price or integer
Example
{
  "attribute": "abc123",
  "frontendInput": "xyz789",
  "label": "xyz789",
  "numeric": true
}
back to top
Types

FixedProductTax

Description

A single FPT that can be applied to a product price

Fields
Field Name Description
amount - Money Amount of the FPT as a money object
label - String The label assigned to the FPT to be displayed on the frontend
Example
{
  "amount": Money,
  "label": "xyz789"
}
back to top
Types

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
987.65
back to top
Types

GiftCardProduct

Description

Defines properties of a gift card, including the minimum and maximum values and an array that contains the current and past values on the specific gift card

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String Relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
weight - Float The weight of the item, in units defined by the store
Example
{
  "add_to_cart_allowed": false,
  "attribute_set_id": 987,
  "canonical_url": "xyz789",
  "created_at": "abc123",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "xyz789",
  "id": 987,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "abc123",
  "meta_title": "xyz789",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "abc123",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "abc123",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": 4,
  "updated_at": "xyz789",
  "weight": 123.45
}
back to top
Types

GroupedProduct

Description

Consists of simple standalone products that are presented as a group

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String Relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
weight - Float The weight of the item, in units defined by the store
Example
{
  "add_to_cart_allowed": true,
  "attribute_set_id": 987,
  "canonical_url": "xyz789",
  "created_at": "xyz789",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "abc123",
  "id": 987,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "abc123",
  "meta_title": "abc123",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "abc123",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "abc123",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": "4",
  "updated_at": "xyz789",
  "weight": 987.65
}
back to top
Types

Highlight

Description

An object that provides highlighted text for matched words

Fields
Field Name Description
attribute - String! The product attribute that contains a match for the search phrase
matched_words - [String]! An array of strings
value - String! The matched text, enclosed within emphasis tags
Example
{
  "attribute": "abc123",
  "matched_words": ["abc123"],
  "value": "abc123"
}
back to top
Types

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example
"4"
back to top
Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
123
back to top
Types

JSON

Description

A JSON scalar

Example
{}
back to top
Types

MediaGalleryInterface

Description

Contains basic information about a product image or video

Fields
Field Name Description
disabled - Boolean Whether the image is hidden from PDP gallery
label - String The label of the product image or video
position - Int The media item's position after it has been sorted
url - String The URL of the product image or video
Possible Types
MediaGalleryInterface Types

ProductImage
Example
{
  "disabled": true,
  "label": "abc123",
  "position": 123,
  "url": "abc123"
}
back to top
Types

Money

Description

A monetary value, including a numeric value and a currency code

Fields
Field Name Description
currency - CurrencyEnum A three-letter currency code, such as USD or EUR
value - Float A number expressing a monetary value
Example
{"currency": "NONE", "value": 987.65}
back to top
Types

PageType

Description

Type of page on which recommendations are requested

Values
Enum Value Description

CMS

Cart

Category

Checkout

PageBuilder

Product
Example
"CMS"
back to top
Types

PhysicalProductInterface

Description

Contains attributes specific to tangible products

Fields
Field Name Description
weight - Float The weight of the item, in units defined by the store
Possible Types
PhysicalProductInterface Types

BundleProduct

ConfigurableProduct

GiftCardProduct

GroupedProduct

SimpleProduct
Example
{"weight": 987.65}
back to top
Types

Price

Description

Defines the price of a simple product or a part of a price range for a complex product. It can include a list of price adjustments.

Fields
Field Name Description
adjustments - [PriceAdjustment] A list of price adjustments.
amount - ProductViewMoney Contains the monetary value and currency code of a product.
Example
{
  "adjustments": [PriceAdjustment],
  "amount": ProductViewMoney
}
back to top
Types

PriceAdjustment

Description

Specifies the amount and type of price adjustment.

Fields
Field Name Description
amount - Float The amount of the price adjustment.
code - String Identifies the type of price adjustment.
Example
{"amount": 987.65, "code": "abc123"}
back to top
Types

PriceRange

Description

Price range for a product. If the product has a single price, the minimum and maximum price will be the same

Fields
Field Name Description
maximum_price - ProductPrice The highest possible price for the product
minimum_price - ProductPrice! The lowest possible price for the product
Example
{
  "maximum_price": ProductPrice,
  "minimum_price": ProductPrice
}
back to top
Types

ProductDiscount

Description

A discount applied to a product price

Fields
Field Name Description
amount_off - Float The actual value of the discount
percent_off - Float The discount expressed a percentage
Example
{"amount_off": 987.65, "percent_off": 987.65}
back to top
Types

ProductImage

Description

Product image information. Contains the image URL and label

Fields
Field Name Description
disabled - Boolean Whether the image is hidden from PDP gallery
label - String The label of the product image or video
position - Int The media item's position after it has been sorted
url - String The URL of the product image or video
Example
{
  "disabled": true,
  "label": "xyz789",
  "position": 123,
  "url": "abc123"
}
back to top
Types

ProductInterface

Description

Contains attributes that are common to all types of products

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String A relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
Possible Types
ProductInterface Types

BundleProduct

ConfigurableProduct

DownloadableProduct

GiftCardProduct

GroupedProduct

SimpleProduct

VirtualProduct
Example
{
  "add_to_cart_allowed": false,
  "attribute_set_id": 123,
  "canonical_url": "xyz789",
  "created_at": "abc123",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "xyz789",
  "id": 123,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "abc123",
  "meta_title": "abc123",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "abc123",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "abc123",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": "4",
  "updated_at": "abc123"
}
back to top
Types

ProductPrice

Description

Product price

Fields
Field Name Description
discount - ProductDiscount The price discount. Represents the difference between the regular and final price
final_price - Money! The final price of the product after discounts applied
fixed_product_taxes - [FixedProductTax] The multiple FPTs that can be applied to a product price
regular_price - Money! The regular price of the product
Example
{
  "discount": ProductDiscount,
  "final_price": Money,
  "fixed_product_taxes": [FixedProductTax],
  "regular_price": Money
}
back to top
Types

ProductSearchItem

Description

A single product returned by the query

Fields
Field Name Description
applied_query_rule - AppliedQueryRule The query rule type that was applied to this product, if any (in preview mode only, returns null otherwise)
highlights - [Highlight] An object that provides highlighted text for matched words
product - ProductInterface! Contains details about the product
productView - ProductView Contains a product view
Example
{
  "applied_query_rule": AppliedQueryRule,
  "highlights": [Highlight],
  "product": ProductInterface,
  "productView": ProductView
}
back to top
Types

ProductSearchResponse

Description

Contains the output of a productSearch query

Fields
Field Name Description
facets - [Aggregation] Details about the static and dynamic facets relevant to the search
items - [ProductSearchItem] An array of products returned by the query
page_info - SearchResultPageInfo Information for rendering pages of search results
related_terms - [String] An array of strings that might include merchant-defined synonyms
suggestions - [String] An array of strings that include the names of products and categories that exist in the catalog that are similar to the search query
total_count - Int The total number of products returned that matched the query
Example
{
  "facets": [Aggregation],
  "items": [ProductSearchItem],
  "page_info": SearchResultPageInfo,
  "related_terms": ["xyz789"],
  "suggestions": ["abc123"],
  "total_count": 987
}
back to top
Types

ProductSearchSortInput

Description

The product attribute to sort on

Fields
Input Field Description
attribute - String! The attribute code of a product attribute
direction - SortEnum! ASC (ascending) or DESC (descending)
Example
{"attribute": "abc123", "direction": "ASC"}
back to top
Types

ProductView

Description

Defines the product fields available to the SimpleProductView and ComplexProductView types.

Fields
Field Name Description
addToCartAllowed - Boolean A flag stating if the product can be added to cart
inStock - Boolean A flag stating if the product is in stock
lowStock - Boolean A flag stating if the product stock is low
attributes - [ProductViewAttribute] A list of merchant-defined attributes designated for the storefront.
Arguments
roles - [String]
description - String The detailed description of the product.
id - ID! The product ID, generated as a composite key, unique per locale.
images - [ProductViewImage] A list of images defined for the product.
Arguments
roles - [String]
videos - [ProductViewVideo] A list of videos defined for the product.
lastModifiedAt - DateTime Date and time when the product was last updated.
metaDescription - String A brief overview of the product for search results listings.
metaKeyword - String A comma-separated list of keywords that are visible only to search engines.
metaTitle - String A string that is displayed in the title bar and tab of the browser and in search results lists.
name - String Product name.
shortDescription - String A summary of the product.
inputOptions - [ProductViewInputOption] A list of input options.
sku - String Product SKU.
externalId - String External Id
url - String Canonical URL of the product.
urlKey - String The URL key of the product.
links - [ProductViewLink] A list of product links.
Arguments
linkTypes - [String!]
categories - [String] List of categories to which the product belongs This field is deprecated and will be removed after Feb 1, 2024.
queryType - String Indicates if the product was retrieved from the primary or the backup query
rank - Int Rank given to a product This field is deprecated and will be removed after Feb 1, 2024.
score - Float Score indicating relevance of the product to the recommendation type This field is deprecated and will be removed after Feb 1, 2024.
visibility - String Visibility setting of the product
Possible Types
ProductView Types

ComplexProductView

SimpleProductView
Example
{
  "addToCartAllowed": true,
  "inStock": true,
  "lowStock": true,
  "attributes": [ProductViewAttribute],
  "description": "abc123",
  "id": "4",
  "images": [ProductViewImage],
  "videos": [ProductViewVideo],
  "lastModifiedAt": "2007-12-03T10:15:30Z",
  "metaDescription": "xyz789",
  "metaKeyword": "xyz789",
  "metaTitle": "abc123",
  "name": "xyz789",
  "shortDescription": "xyz789",
  "inputOptions": [ProductViewInputOption],
  "sku": "abc123",
  "externalId": "abc123",
  "url": "abc123",
  "urlKey": "abc123",
  "links": [ProductViewLink],
  "categories": ["xyz789"],
  "queryType": "xyz789",
  "rank": 123,
  "score": 123.45,
  "visibility": "xyz789"
}
back to top
Types

ProductViewAttribute

Description

A container for customer-defined attributes that are displayed the storefront.

Fields
Field Name Description
label - String Label of the attribute.
name - String! Name of an attribute code.
roles - [String] Roles designated for an attribute on the storefront, such as "Show on PLP", "Show in PDP", or "Show in Search".
value - JSON Attribute value, arbitrary of type.
Example
{
  "label": "abc123",
  "name": "xyz789",
  "roles": ["xyz789"],
  "value": {}
}
back to top
Types

ProductViewCurrency

Description

The list of supported currency codes.

Values
Enum Value Description

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

AWG

AZM

AZN

BAM

BBD

BDT

BGN

BHD

BIF

BMD

BND

BOB

BRL

BSD

BTN

BUK

BWP

BYN

BZD

CAD

CDF

CHE

CHF

CHW

CLP

CNY

COP

CRC

CUP

CVE

CZK

DJF

DKK

DOP

DZD

EEK

EGP

ERN

ETB

EUR

FJD

FKP

GBP

GEK

GEL

GHS

GIP

GMD

GNF

GQE

GTQ

GYD

HKD

HNL

HRK

HTG

HUF

IDR

ILS

INR

IQD

IRR

ISK

JMD

JOD

JPY

KES

KGS

KHR

KMF

KPW

KRW

KWD

KYD

KZT

LAK

LBP

LKR

LRD

LSL

LSM

LTL

LVL

LYD

MAD

MDL

MGA

MKD

MMK

MNT

MOP

MRO

MUR

MVR

MWK

MXN

MYR

MZN

NAD

NGN

NIC

NOK

NPR

NZD

OMR

PAB

PEN

PGK

PHP

PKR

PLN

PYG

QAR

RHD

ROL

RON

RSD

RUB

RWF

SAR

SBD

SCR

SDG

SEK

SGD

SHP

SKK

SLL

SOS

SRD

STD

SVC

SYP

SZL

THB

TJS

TMM

TND

TOP

TRL

TRY

TTD

TWD

TZS

UAH

UGX

USD

UYU

UZS

VEB

VEF

VND

VUV

WST

XCD

XOF

XPF

YER

ZAR

ZMK

ZWD

NONE
Example
"AED"
back to top
Types

ProductViewImage

Description

Contains details about a product image.

Fields
Field Name Description
label - String The display label of the product image.
roles - [String] A list that describes how the image is used. Can be image, small_image, or thumbnail.
url - String! The URL to the product image.
Example
{
  "label": "abc123",
  "roles": ["xyz789"],
  "url": "abc123"
}
back to top
Types

ProductViewInputOption

Description

Product options provide a way to configure products by making selections of particular option values. Selecting one or many options will point to a simple product.

Fields
Field Name Description
id - ID The ID of an option value
title - String The display name of the option value
required - Boolean Wether this option is required or not
type - String The type of data entry
markupAmount - Float Price markup or markdown
suffix - String SKU suffix to add to the product
sortOrder - Int Sort order
range - ProductViewInputOptionRange
imageSize - ProductViewInputOptionImageSize
fileExtensions - String
Example
{
  "id": "4",
  "title": "xyz789",
  "required": false,
  "type": "abc123",
  "markupAmount": 123.45,
  "suffix": "abc123",
  "sortOrder": 987,
  "range": ProductViewInputOptionRange,
  "imageSize": ProductViewInputOptionImageSize,
  "fileExtensions": "abc123"
}
back to top
Types

ProductViewInputOptionImageSize

Fields
Field Name Description
width - Int
height - Int
Example
{"width": 987, "height": 123}
back to top
Types

ProductViewInputOptionRange

Fields
Field Name Description
from - Float
to - Float
Example
{"from": 987.65, "to": 987.65}
back to top
Types

ProductViewMoney

Description

Defines a monetary value, including a numeric value and a currency code.

Fields
Field Name Description
currency - ProductViewCurrency A three-letter currency code, such as USD or EUR.
value - Float A number expressing a monetary value.
Example
{"currency": "AED", "value": 123.45}
back to top
Types

ProductViewOption

Description

Product options provide a way to configure products by making selections of particular option values. Selecting one or many options will point to a simple product.

Fields
Field Name Description
id - ID The ID of the option.
multi - Boolean Indicates whether the option allows multiple choices.
required - Boolean Indicates whether the option must be selected.
title - String The display name of the option.
values - [ProductViewOptionValue!] List of available option values.
Example
{
  "id": "4",
  "multi": true,
  "required": false,
  "title": "abc123",
  "values": [ProductViewOptionValue]
}
back to top
Types

ProductViewOptionValue

Description

Defines the product fields available to the ProductViewOptionValueProduct and ProductViewOptionValueConfiguration types.

Fields
Field Name Description
id - ID The ID of an option value.
title - String The display name of the option value.
inStock - Boolean Indicates if the option is in stock.
Possible Types
ProductViewOptionValue Types

ProductViewOptionValueConfiguration

ProductViewOptionValueProduct

ProductViewOptionValueSwatch
Example
{
  "id": "4",
  "title": "xyz789",
  "inStock": true
}
back to top
Types

ProductViewOptionValueConfiguration

Description

An implementation of ProductViewOptionValue for configuration values.

Fields
Field Name Description
id - ID The ID of an option value.
title - String The display name of the option value.
inStock - Boolean Indicates if the option is in stock.
Example
{
  "id": "4",
  "title": "xyz789",
  "inStock": false
}
back to top
Types

ProductViewOptionValueProduct

Description

An implementation of ProductViewOptionValue that adds details about a simple product.

Fields
Field Name Description
id - ID The ID of an option value.
isDefault - Boolean States if the option value is default or not.
product - SimpleProductView Details about a simple product.
quantity - Float Default quantity of an option value.
title - String The display name of the option value.
inStock - Boolean Indicates if the option is in stock.
enabled - Boolean Indicates if the associated product is enabled.
Example
{
  "id": 4,
  "isDefault": false,
  "product": SimpleProductView,
  "quantity": 123.45,
  "title": "xyz789",
  "inStock": true,
  "enabled": false
}
back to top
Types

ProductViewOptionValueSwatch

Description

An implementation of ProductViewOptionValueSwatch for swatches.

Fields
Field Name Description
id - ID The ID of an option value.
title - String The display name of the option value.
type - SwatchType Indicates the type of the swatch.
value - String The value of the swatch depending on the type of the swatch.
inStock - Boolean Indicates if the option is in stock.
Example
{
  "id": 4,
  "title": "abc123",
  "type": "TEXT",
  "value": "abc123",
  "inStock": false
}
back to top
Types

ProductViewPrice

Description

Base product price view, inherent for simple products.

Fields
Field Name Description
final - Price Price value after discounts, excluding personalized promotions.
regular - Price Base product price specified by the merchant.
roles - [String] Price roles, stating if the price should be visible or hidden.
Example
{
  "final": Price,
  "regular": Price,
  "roles": ["xyz789"]
}
back to top
Types

ProductViewPriceRange

Description

The minimum and maximum price of a complex product.

Fields
Field Name Description
maximum - ProductViewPrice Maximum price.
minimum - ProductViewPrice Minimum price.
Example
{
  "maximum": ProductViewPrice,
  "minimum": ProductViewPrice
}
back to top
Types

ProductViewVariant

Fields
Field Name Description
selections - [String!] List of option values that make up the variant.
product - ProductView Product corresponding to the variant.
Example
{
  "selections": ["xyz789"],
  "product": ProductView
}
back to top
Types

ProductViewVariantResults

Fields
Field Name Description
variants - [ProductViewVariant]! List of product variants.
cursor - String Pagination cursor
Example
{
  "variants": [ProductViewVariant],
  "cursor": "abc123"
}
back to top
Types

ProductViewVideo

Description

Contains details about a product video

Fields
Field Name Description
preview - ProductViewImage Preview image for the video
url - String! The URL to the product video.
description - String Description of the product video.
title - String The title of the product video.
Example
{
  "preview": ProductViewImage,
  "url": "abc123",
  "description": "abc123",
  "title": "xyz789"
}
back to top
Types

PurchaseHistory

Description

User purchase history

Fields
Input Field Description
date - DateTime
items - [String]!
Example
{
  "date": "2007-12-03T10:15:30Z",
  "items": ["xyz789"]
}
back to top
Types

QueryContextInput

Fields
Input Field Description
customerGroup - String! The customer group code. Field reserved for future use. Currently, passing this field will have no impact on search results, that is, the search results will be for "Not logged in" customer
userViewHistory - [ViewHistoryInput!] User view history with timestamp
Example
{
  "customerGroup": "abc123",
  "userViewHistory": [ViewHistoryInput]
}
back to top
Types

RangeBucket

Description

For use on numeric product fields

Fields
Field Name Description
count - Int! The number of items in the bucket
from - Float! The minimum amount in a price range
title - String! The display text defining the price range
to - Float The maximum amount in a price range
Example
{
  "count": 987,
  "from": 123.45,
  "title": "xyz789",
  "to": 123.45
}
back to top
Types

RecommendationUnit

Description

Recommendation Unit containing product and other details

Fields
Field Name Description
displayOrder - Int Order in which recommendation units are displayed
pageType - String Page type
productsView - [ProductView] List of product view
storefrontLabel - String Storefront label to be displayed on the storefront
totalProducts - Int Total products returned in recommedations
typeId - String Type of recommendation
unitId - String Id of the preconfigured unit
unitName - String Name of the preconfigured unit
Example
{
  "displayOrder": 123,
  "pageType": "xyz789",
  "productsView": [ProductView],
  "storefrontLabel": "abc123",
  "totalProducts": 123,
  "typeId": "xyz789",
  "unitId": "abc123",
  "unitName": "xyz789"
}
back to top
Types

Recommendations

Description

Recommendations response

Fields
Field Name Description
results - [RecommendationUnit] List of rec units with products recommended
totalResults - Int total number of rec units for which recommendations are returned
Example
{"results": [RecommendationUnit], "totalResults": 123}
back to top
Types

ScalarBucket

Description

For use on string and other scalar product fields

Fields
Field Name Description
count - Int! The number of items in the bucket
id - ID! An identifier that can be used for filtering. It may contain non-human readable data
title - String! The display text for the scalar value
Example
{
  "count": 123,
  "id": "4",
  "title": "abc123"
}
back to top
Types

SearchClauseInput

Description

A product attribute to filter on

Fields
Input Field Description
attribute - String! The attribute code of a product attribute
eq - String A string value to filter on
in - [String] An array of string values to filter on
range - SearchRangeInput A range of numeric values to filter on
startsWith - String Attribute value should start with the specified string
contains - String Attribute value should contain the specified string
Example
{
  "attribute": "xyz789",
  "eq": "abc123",
  "in": ["abc123"],
  "range": SearchRangeInput,
  "startsWith": "abc123",
  "contains": "abc123"
}
back to top
Types

SearchRangeInput

Description

A range of numeric values for use in a search

Fields
Input Field Description
from - Float The minimum value to filter on. If not specified, the value of 0 is applied
to - Float The maximum value to filter on
Example
{"from": 123.45, "to": 123.45}
back to top
Types

SearchResultPageInfo

Description

Provides navigation for the query response

Fields
Field Name Description
current_page - Int Specifies which page of results to return
page_size - Int Specifies the maximum number of items to return
total_pages - Int Specifies the total number of pages returned
Example
{"current_page": 123, "page_size": 987, "total_pages": 987}
back to top
Types

SimpleProduct

Description

A simple product is tangible and is usually sold in single units or in fixed quantities

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String A relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute]
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
weight - Float The weight of the item, in units defined by the store
Example
{
  "add_to_cart_allowed": false,
  "attribute_set_id": 123,
  "canonical_url": "xyz789",
  "created_at": "xyz789",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "xyz789",
  "id": 987,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "abc123",
  "meta_title": "xyz789",
  "name": "abc123",
  "new_from_date": "abc123",
  "new_to_date": "abc123",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "xyz789",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": "4",
  "updated_at": "xyz789",
  "weight": 987.65
}
back to top
Types

SimpleProductView

Description

Represents simple products. Simple product prices do not contain price ranges.

Fields
Field Name Description
addToCartAllowed - Boolean A flag stating if the product can be added to cart
inStock - Boolean A flag stating if the product is in stock
lowStock - Boolean A flag stating if the product stock is low
attributes - [ProductViewAttribute] A list of merchant-defined attributes designated for the storefront.
Arguments
roles - [String]
description - String The detailed description of the product.
id - ID! The product ID, generated as a composite key, unique per locale.
images - [ProductViewImage] A list of images defined for the product.
Arguments
roles - [String]
videos - [ProductViewVideo] A list of videos defined for the product.
inputOptions - [ProductViewInputOption] A list of input options.
lastModifiedAt - DateTime Date and time when the product was last updated.
metaDescription - String A brief overview of the product for search results listings.
metaKeyword - String A comma-separated list of keywords that are visible only to search engines.
metaTitle - String A string that is displayed in the title bar and tab of the browser and in search results lists.
name - String Product name.
price - ProductViewPrice Base product price view.
shortDescription - String A summary of the product.
sku - String Product SKU.
externalId - String External Id
url - String Canonical URL of the product.
urlKey - String The URL key of the product.
links - [ProductViewLink] A list of product links
Arguments
linkTypes - [String!]
categories - [String] List of categories to which the product belongs This field is deprecated and will be removed after Feb 1, 2024.
queryType - String Indicates if the product was retrieved from the primary or the backup query
rank - Int Rank given to a product This field is deprecated and will be removed after Feb 1, 2024.
score - Float Score indicating relevance of the product to the recommendation type This field is deprecated and will be removed after Feb 1, 2024.
visibility - String Visibility setting of the product
Example
{
  "addToCartAllowed": true,
  "inStock": false,
  "lowStock": true,
  "attributes": [ProductViewAttribute],
  "description": "xyz789",
  "id": 4,
  "images": [ProductViewImage],
  "videos": [ProductViewVideo],
  "inputOptions": [ProductViewInputOption],
  "lastModifiedAt": "2007-12-03T10:15:30Z",
  "metaDescription": "abc123",
  "metaKeyword": "xyz789",
  "metaTitle": "xyz789",
  "name": "abc123",
  "price": ProductViewPrice,
  "shortDescription": "xyz789",
  "sku": "abc123",
  "externalId": "abc123",
  "url": "abc123",
  "urlKey": "abc123",
  "links": [ProductViewLink],
  "categories": ["abc123"],
  "queryType": "xyz789",
  "rank": 987,
  "score": 123.45,
  "visibility": "xyz789"
}
back to top
Types

SortEnum

Description

This enumeration indicates whether to return results in ascending or descending order

Values
Enum Value Description

ASC

DESC
Example
"ASC"
back to top
Types

SortableAttribute

Description

Contains product attributes that be used for sorting in a productSearch query

Fields
Field Name Description
attribute - String! The unique identifier for an attribute code. This value should be in lowercase letters and without space
frontendInput - String Indicates how field rendered on storefront
label - String The display name assigned to the attribute
numeric - Boolean Indicates whether this attribute has a numeric value, such as a price or integer
Example
{
  "attribute": "xyz789",
  "frontendInput": "xyz789",
  "label": "abc123",
  "numeric": true
}
back to top
Types

StatsBucket

Description

For retrieving statistics across multiple buckets

Fields
Field Name Description
max - Float! The maximum value
min - Float! The minimum value
title - String! The display text for the bucket
Example
{
  "max": 123.45,
  "min": 987.65,
  "title": "xyz789"
}
back to top
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"abc123"
back to top
Types

SwatchType

Values
Enum Value Description

TEXT

IMAGE

COLOR_HEX

CUSTOM
Example
"TEXT"
back to top
Types

ViewHistory

Description

User view history

Fields
Input Field Description
date - DateTime
sku - String!
Example
{
  "date": "2007-12-03T10:15:30Z",
  "sku": "xyz789"
}
back to top
Types

ViewHistoryInput

Description

User view history

Fields
Input Field Description
dateTime - DateTime
sku - String!
Example
{
  "dateTime": "2007-12-03T10:15:30Z",
  "sku": "abc123"
}
back to top
Types

VirtualProduct

Description

A non-tangible product that does not require shipping and is not kept in inventory

Fields
Field Name Description
add_to_cart_allowed - Boolean Boolean indicating whether a product can be added to cart. Field reserved for future use. Currently, will default to true
attribute_set_id - Int The attribute set assigned to the product
canonical_url - String Relative canonical URL
created_at - String Timestamp indicating when the product was created
custom_attributes - [CustomAttribute] An array of custom product attributes
description - ComplexTextValue Detailed information about the product. The value can include simple HTML tags
gift_message_available - String Indicates whether a gift message is available
id - Int id Magento 2.4 has not yet deprecated the ProductInterface.id field
image - ProductImage The relative path to the main image on the product page
media_gallery - [MediaGalleryInterface] An array of Media Gallery objects
meta_description - String A brief overview of the product for search results listings, maximum 255 characters
meta_keyword - String A comma-separated list of keywords that are visible only to search engines
meta_title - String A string that is displayed in the title bar and tab of the browser and in search results lists
name - String The product name. Customers use this name to identify the product
new_from_date - String The beginning date for new product listings, and determines if the product is featured as a new product
new_to_date - String The end date for new product listings
price_range - PriceRange! A PriceRange object, indicating the range of prices for the product
short_description - ComplexTextValue A short description of the product. Its use depends on the theme
sku - String A number or code assigned to a product to identify the product, options, price, and manufacturer
small_image - ProductImage The relative path to the small image, which is used on catalog pages
thumbnail - ProductImage The relative path to the product's thumbnail image
uid - ID! The unique ID for a ProductInterface object
updated_at - String Timestamp indicating when the product was updated
Example
{
  "add_to_cart_allowed": false,
  "attribute_set_id": 123,
  "canonical_url": "xyz789",
  "created_at": "abc123",
  "custom_attributes": [CustomAttribute],
  "description": ComplexTextValue,
  "gift_message_available": "xyz789",
  "id": 987,
  "image": ProductImage,
  "media_gallery": [MediaGalleryInterface],
  "meta_description": "abc123",
  "meta_keyword": "xyz789",
  "meta_title": "xyz789",
  "name": "xyz789",
  "new_from_date": "xyz789",
  "new_to_date": "xyz789",
  "price_range": PriceRange,
  "short_description": ComplexTextValue,
  "sku": "xyz789",
  "small_image": ProductImage,
  "thumbnail": ProductImage,
  "uid": 4,
  "updated_at": "xyz789"
}
back to top
Documentation by Anvil SpectaQL