refineProduct query
The refineProduct query helps narrow down the results of a products query that was run against a complex product. To use this query effectively, first run the products query and ensure that the response includes a list of options within a ComplexProductView inline fragment. When a shopper selects a product option (such as size or color) on the storefront, you can then run the refineProduct query by specifying the SKU and the selected option value IDs as input. Depending on the number of product options available for the complex product, you might need to run the refineProduct query multiple times until the shopper has selected a specific variant.
Ensure that your query response includes both the ComplexProductView and SimpleProductView inline fragments. If the shopper has not selected all required options, the query returns the IDs of unselected options along with the minimum and maximum price of the product, based on the selected options and possible remaining options. If all required options are selected, the query returns details about a simple product, including its set price.
Syntax
refineProduct(sku: String!, optionIds: [String!]!): ProductView
Endpoints
data-src=../../../../includes/graphql/endpoints.md
Required headers
You must specify the following HTTP headers to run this query.
data-src=../../../../includes/graphql/catalog-service/headers.md
Find the customer group code
data-src=../../../../includes/graphql/customer-group-code.md
Example usage
Return details about a partially selected complex product
The following query returns details about the color options available for a medium-sized variant of product MH12. The value of the optionIDs input parameter is taken from the products query's Return details about a complex product example.
data-slots=heading, code
data-repeat=2
data-languages=JSON
query {
refineProduct(optionIds: ["Y29uZmlndXJhYmxlLzE4Ni8xNzc="], sku: "MH12") {
__typename
id
sku
name
url
... on SimpleProductView {
price {
final {
amount {
value
}
}
regular {
amount {
value
}
}
}
}
... on ComplexProductView {
options {
id
title
required
values {
id
title
}
}
priceRange {
maximum {
final {
amount {
value
}
}
regular {
amount {
value
}
}
}
minimum {
final {
amount {
value
}
}
regular {
amount {
value
}
}
}
}
}
}
}
{
"data": {
"refineProduct": {
"__typename": "ComplexProductView",
"id": "VFVneE1nAFpHVm1ZWFZzZEEATXpSbE1qYzBNR0V0TnpRM015MDBZemc1TFRnM016QXROVGMwTURObVkyVXlOMkZsAGJXRnBibDkzWldKemFYUmxYM04wYjNKbABZbUZ6WlEAVFVGSFUxUkhNREExTlRjNU1ETTQ",
"sku": "MH12",
"name": "Ajax Full-Zip Sweatshirt 2",
"url": "http://example.com/ajax-full-zip-sweatshirt.html",
"options": [
{
"id": "color",
"title": "Color",
"required": false,
"values": [
{
"id": "Y29uZmlndXJhYmxlLzkzLzU5",
"title": "Blue"
},
{
"id": "Y29uZmlndXJhYmxlLzkzLzY3",
"title": "Red"
},
{
"id": "Y29uZmlndXJhYmxlLzkzLzYy",
"title": "Green"
}
]
}
],
"priceRange": {
"maximum": {
"final": {
"amount": {
"value": 69
}
},
"regular": {
"amount": {
"value": 69
}
}
},
"minimum": {
"final": {
"amount": {
"value": 69
}
},
"regular": {
"amount": {
"value": 69
}
}
}
}
}
}
}
Return details about a fully selected complex product
In the following query, the shopper has selected options for both size and color. The response contains details about the corresponding simple product.
data-slots=heading, code
data-repeat=3
data-languages=JSON
query {
refineProduct(optionIds: ["Y29uZmlndXJhYmxlLzE4Ni8xNzc=", "Y29uZmlndXJhYmxlLzkzLzU5"], sku: "MH12") {
__typename
id
sku
name
url
... on SimpleProductView {
price {
final {
amount {
value
}
}
regular {
amount {
value
}
}
}
}
... on ComplexProductView {
options {
id
title
required
values {
id
title
}
}
priceRange {
maximum {
final {
amount {
value
}
}
regular {
amount {
value
}
}
}
minimum {
final {
amount {
value
}
}
regular {
amount {
value
}
}
}
}
}
}
}
{
"data": {
"refineProduct": {
"__typename": "SimpleProductView",
"id": "VFVneE1pMU5MVUpzZFdVAFpHVm1ZWFZzZEEATXpSbE1qYzBNR0V0TnpRM015MDBZemc1TFRnM016QXROVGMwTURObVkyVXlOMkZsAGJXRnBibDkzWldKemFYUmxYM04wYjNKbABZbUZ6WlEAVFVGSFUxUkhNREExTlRjNU1ETTQ",
"sku": "MH12-M-Blue",
"name": "Ajax Full-Zip Sweatshirt -M-Blue",
"url": "http://example.com/catalog/product/view/id/235/s/ajax-full-zip-sweatshirt-m-blue/",
"price": {
"final": {
"amount": {
"value": 69
}
},
"regular": {
"amount": {
"value": 69
}
}
}
}
}
}
Input fields
optionIdsskuOutput fields
The ProductView return object is an interface that can contain the following fields. It is implemented by the SimpleProductView and ComplexProductView types.
addToCartAllowedattributes(roles: [String])descriptionexternalIdidinputOptionsinStocklastModifiedAtlowStockmetaDescriptionmetaKeywordmetaTitlenameshortDescriptionskuurlurlKeyComplexProductView type
The ComplexProductView type represents bundle, configurable, and group products. Complex product prices are returned as a price range, because price values can vary based on selected options. The type implements ProductView.
addToCartAllowedattributes(roles: [String])descriptionexternalIdidinputOptionsinStocklowStockmetaDescriptionmetaKeywordmetaTitlenameshortDescriptionskuurlurlKeyvideos[ProductViewVideo](#productviewvideo-type)Price type
The Price type 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.
PriceAdjustment type
The PriceAdjustment type specifies the amount and type of a price adjustment. An example code value is weee.
amountcodeProductViewAttribute type
The ProductViewAttribute type is a container for customer-defined attributes that are displayed the storefront.
labelnamerolesvalueProductViewImage type
The ProductViewImage type contains details about a product image.
labelrolesimage, small_image, or thumbnail.urlProductViewLink type
The ProductViewLink type contains details about product links for related products and cross selling.
linkTypescrosssell, related, and upsell.productProductView!ProductViewMoney type
The ProductViewMoney type defines a monetary value, including a numeric value and a currency code.
currencyvalueProductViewInputOption type
Product input options provide details about how a shopper can enter customization details for a product. For example, for product personalization the input options might provide the fields for the shopper to add an image or text for a monogram. The input option can include an associated markupAmount that is applied to the product price. For additional information, see Product settings - Customizable Options.
fileExtensionspng, jpg.idmarkupAmountrangerequiredsortOrdersuffixtitletypetextfield, textarea, date, date_time, time, file.ProductViewInputOptionRange type
Lists the value range associated with a [ProductViewInputOption]. For example, if the input option is a text field, the range represents the number of characters.
fromtoProductViewInputOptionImageSize type
Lists the image dimensions for an image associated with a [ProductViewInputOption].
heightwidthProductViewOption type
Product options provide a way to configure products by making selections of particular option values predefined for the product. Selecting one or many options points to a specific simple product.
idmultirequiredtitleProductViewOptionValue interface
The ProductViewOptionValue interface defines the product fields available to the ProductViewOptionValueProduct and ProductViewOptionValueConfiguration types.
idinStocktitleProductViewOptionValueConfiguration type
The ProductViewOptionValueConfiguration type is an implementation of ProductViewOptionValue for configuration values.
idinStocktitleProductViewOptionValueProduct type
The ProductViewOptionValueProduct type is an implementation of ProductViewOptionValue that adds details about a simple product.
idinStockisDefaulttitleProductViewOptionValueSwatch type
The ProductViewOptionValueSwatch type is an implementation of ProductViewOptionValue that adds details about a product swatch.
idinStocktitletypeTEXT, IMAGE, COLOR_HEX, or CUSTOM.valueProductViewPrice type
The ProductViewPrice type provides the base product price view, inherent for simple products.
finalregularrolesProductViewPriceRange type
The ProductViewPriceRange type lists the minimum and maximum price of a complex product.
maximumminimumProductViewVideo type
urldescriptiontitleSimpleProductView type
The SimpleProductView type represents all product types, except bundle, configurable, and group. Simple product prices do not contain price ranges. SimpleProductView implements ProductView.
addToCartAllowedattributes(roles: [String])descriptionexternalIdidinputOptionsinStocklowStockmetaDescriptionmetaKeywordmetaTitlenameshortDescriptionskuurlurlKey