From 711e45df8de123c7a92111fe8de548a7b86f81bb Mon Sep 17 00:00:00 2001 From: bc-andreadao <96258747+bc-andreadao@users.noreply.github.com> Date: Thu, 21 Sep 2023 11:29:54 -0500 Subject: [PATCH] DEVDOCS-4244: [net new] Storefront GraphQL products and variants (#1625) Co-authored-by: Tina Gomez Co-authored-by: Sarah Riehl --- .../graphql/graphql-api-examples.mdx | 217 ----- .../graphql/graphql-api-overview.mdx | 2 + .../storefront/graphql/graphql-products.mdx | 876 ++++++++++++++++++ .../storefront/graphql/graphql-variants.mdx | 801 ++++++++++++++++ 4 files changed, 1679 insertions(+), 217 deletions(-) create mode 100644 docs/api-docs/storefront/graphql/graphql-products.mdx create mode 100644 docs/api-docs/storefront/graphql/graphql-variants.mdx diff --git a/docs/api-docs/storefront/graphql/graphql-api-examples.mdx b/docs/api-docs/storefront/graphql/graphql-api-examples.mdx index 4bde5155c..bf4914ad6 100644 --- a/docs/api-docs/storefront/graphql/graphql-api-examples.mdx +++ b/docs/api-docs/storefront/graphql/graphql-api-examples.mdx @@ -193,223 +193,6 @@ query LookUpUrl { **Try it in GraphQL Playground** -## Get product images at different resolutions - -```graphql filename="Example query: Get product images at different resolutions" showLineNumbers copy -query SrcsetImages { - site { - product(entityId: 123) { - images { - edges { - node { - url320wide: url(width: 320) - url640wide: url(width: 640) - url960wide: url(width: 960) - url1280wide: url(width: 1280) - } - } - } - } - } -} -``` - -**Try it in GraphQL Playground** - -## Get a product - -```graphql filename="Example query: Get a product" showLineNumbers copy -query SingleProduct { - site { - products (entityIds: [4917]) { - edges { - node { - id - entityId - name - prices { - price { - value - currencyCode - } - } - } - } - } - } -} -``` - -**Try it in GraphQL Playground** - -## Get variant details as a product object - -```graphql filename="Example query: Get variant details as a product object" showLineNumbers copy -query VariantById { - site { - product(variantEntityId: 27098) { - name - sku - defaultImage { - url(width: 500, height: 500) - } - prices { - price { - ...PriceFields - } - salePrice { - ...PriceFields - } - retailPrice { - ...PriceFields - } - } - width { - ...DimensionFields - } - height { - ...DimensionFields - } - depth { - ...DimensionFields - } - } - } -} -fragment PriceFields on Money { - value - currencyCode -} -fragment DimensionFields on Measurement { - value - unit -} -``` - - -This query returns variant information appropriately overlaid on the Product object. For example, if the variant has a different image, dimensions, SKU, or price, that will be automatically returned -- this allows for directly merchandising particular variants. - - -
- -**Try it in GraphQL Playground** - -## Get product option details by product ID - -```graphql filename="Example query: Get product option details by product ID" showLineNumbers copy -query SeveralProductsByID { - site { - products(entityIds: [1, 2, 3]) { - edges { - node { - name - productOptions { - edges { - node { - entityId - displayName - isRequired - ... on MultipleChoiceOption { - values { - edges { - node { - entityId - label - } - } - } - } - } - } - } - } - } - } - } -} -``` - -**Try it in GraphQL Playground** - -## Get refined product object for given options - -```graphql filename="Example query: Get refined product object for given options" showLineNumbers copy -query ProductsWithOptionSelections { - site { - product123: product( - entityId: 123 - optionValueIds: [ - { optionEntityId: 4, valueEntityId: 543 } - { optionEntityId: 5, valueEntityId: 443 } - ] - ) { - ...ProductFields - } - product234: product( - entityId: 234 - optionValueIds: [ - { optionEntityId: 8, valueEntityId: 768 } - { optionEntityId: 13, valueEntityId: 883 } - ] - ) { - ...ProductFields - } - } -} - -fragment ProductFields on Product { - name - defaultImage { - url(width: 1000) - } - sku -} -``` - -**Try it in GraphQL Playground** - -## Get product swatch option values - -```graphql filename="Example query: Get product swatch option values" showLineNumbers copy -query { - site { - products (first: 3) { - pageInfo { - startCursor - endCursor - } - edges { - cursor - node { - entityId - name - productOptions { - edges { - node { - entityId - displayName - ... on MultipleChoiceOption { - values { - edges { - node { - ... on SwatchOptionValue { - label - hexColors - } - } - } - } - } - } - } - } - } - } - } - } -} -``` - ## Get popular brands ```graphql filename="Example query: Get popular brands" showLineNumbers copy diff --git a/docs/api-docs/storefront/graphql/graphql-api-overview.mdx b/docs/api-docs/storefront/graphql/graphql-api-overview.mdx index 1ec7d696e..e5dd291a2 100644 --- a/docs/api-docs/storefront/graphql/graphql-api-overview.mdx +++ b/docs/api-docs/storefront/graphql/graphql-api-overview.mdx @@ -499,6 +499,8 @@ query brands { } ``` +If `first` is not specified, a query returns only 10 items by default. + ## Complexity limits Complexity scores estimate the load that a single GraphQL request may generate. BigCommerce calculates the complexity score using an algorithm before executing the call, based on the provided query. diff --git a/docs/api-docs/storefront/graphql/graphql-products.mdx b/docs/api-docs/storefront/graphql/graphql-products.mdx new file mode 100644 index 000000000..55d5744d9 --- /dev/null +++ b/docs/api-docs/storefront/graphql/graphql-products.mdx @@ -0,0 +1,876 @@ +**GraphQL Storefront API** +# Guide to Working with Products + +BigCommerce's GraphQL Storefront API lets frontend developers retrieve [products](/docs/rest-catalog/products) from a store. These built-in capabilities allow developers to customize their hosted and headless storefronts with product information. + +The GraphQL Storefront API lets you retrieve the following product attributes and more: +- Price information in a store's transacting currency +- Product options associated with a product, both variant and modifier options +- Product metafields that have storefront access + +You can access these attributes for a product if a merchant makes a product visible on storefronts. + +This guide walks you through the process of retrieving information for a product. If your product has variants, see [Guide to Working with Product Variants](/api-docs/storefront/graphql/variants) on how to retrieve variant information. For full schema documentation, see the [GraphQL Storefront Playground](https://developer.bigcommerce.com/graphql-storefront/playground). + +## Get a Product + +### Get a product with the product field + +You can query a product by using the `product` field and specifying a product identifier, for example, the product `entityId`. + +```graphql filename="Get a product with the product field" showLineNumbers copy +# This query retrieves one product. + +query { + site { + product (entityId: 111) { + # fields on the Product object type + } + } +} +``` + +```graphql filename="Get a product with the product field" showLineNumbers copy +# This query retrieves two products. +# This query uses aliases and fragments. To learn more about queries, see https://graphql.org/learn/queries. + +query { + site { + product1: product(entityId: 113) { + ...ProductFields + } + product2: product(entityId: 115) { + ...ProductFields + } + } +} + +fragment ProductFields on Product { + # fields on the Product object type +} +``` + + + #### Get product versus variant + The Product object is also used to retrieve variant information. For example, if you use the identifier `variantEntityId` or `optionValueIds`, you will retrieve information for the variant overlaid on the Product object (if the variant has a different values than the product). + See [Get a variant](/api-docs/storefront/graphql/variants#get-a-variant) for more information. + + +### Get a product with the products field + +Query a list of products by using the `products` field and specifying product identifiers, for example, the product `entityID`s: + +```graphql filename="Get a product with the products field" showLineNumbers copy +# This example retrieves one product. +# Specify multiple entityIds to retrieve multiple products. + +query { + site { + products (entityIds: [111]) { + edges { + node { + # fields on the Product object type + } + } + } + } +} +``` + +Query all products by not including an argument for `products`. + +You can also query for featured products, related products, and more. See the [GraphQL Storefront Playground](https://developer.bigcommerce.com/graphql-storefront/playground) for full schema documentation. + +## Get product identifiers + +Query basic information for products. The following query retrieves both product identifiers and basic information for the specified product: + + + + + ```graphql filename="Example query: Get basic information for a product" showLineNumbers copy + query { + site { + product (entityId: 111) { + id + entityId + sku + path + name + description + addToCartUrl + upc + mpn + gtin + } + } + } + ``` + + + + + ```json filename="Example response: Get basic information for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "id": "UHJvZHVjdDoxMTE=", + "entityId": 111, + "sku": "SM13", + "path": "/smith-journal-13/", + "name": "[Sample] Smith Journal 13", + "description": "

143 Pages

", + "addToCartUrl": "https://example-store.mybigcommerce.com/cart.php?action=add&product_id=111", + "upc": "123456", + "mpn": "example MPN", + "gtin": "99999999" + } + } + } + } + ``` + + + +## Get product prices and dimensions + +Query prices and dimensions for a product. The following query retrieves prices and dimensions for the specified product: + + + + + + ```graphql filename="Example query: Get prices and dimensions for a product" showLineNumbers copy + # This query uses fragments. To learn more about fragments, see https://graphql.org/learn/queries/#fragments. + + query { + site { + product (entityId: 111) { + prices(currencyCode: USD) { + price { + ...PriceFields + } + salePrice { + ...PriceFields + } + basePrice { + ...PriceFields + } + retailPrice { + ...PriceFields + } + } + weight { + ...DimensionFields + } + height { + ...DimensionFields + } + width { + ...DimensionFields + } + depth { + ...DimensionFields + } + } + } + } + + # fields on the Money object type + fragment PriceFields on Money { + currencyCode + value + } + + # fields on the Measurement object type + fragment DimensionFields on Measurement { + value + unit + } + ``` + + + + + ```json filename="Example response: Get prices and dimensions for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "prices": { + "price": { + "currencyCode": "USD", + "value": 5 + }, + "salePrice": { + "currencyCode": "USD", + "value": 5 + }, + "basePrice": { + "currencyCode": "USD", + "value": 25 + }, + "retailPrice": { + "currencyCode": "USD", + "value": 200 + } + }, + "weight": { + "value": 4000, + "unit": "oz" + }, + "height": { + "value": 4, + "unit": "in" + }, + "width": { + "value": 4, + "unit": "in" + }, + "depth": { + "value": 4, + "unit": "in" + } + } + } + } + } + ``` + + + +## Get product options + +Query the [product options](/docs/rest-catalog/product-variant-options) associated with a product. The response includes both variant options and modifier options. To retrieve only variant options, use a [Get variant options](/api-docs/storefront/graphql/variants#get-variant-options) query. + +There are various types of product options available. Checkbox and multiple choice are some examples of the many option types available. Each type of product option has a schema type that implements the `CatalogProductOption` interface, meaning you can retrieve the common fields from `CatalogProductOption` for any type of product option. For more on interfaces, see the [GraphQL Schema and Types- Interfaces (graphql.org)](https://graphql.org/learn/schema#interfaces) documentation. + +```graphql filename="CatalogProductOption interface" showLineNumbers copy +# Fields common among product option types + +interface CatalogProductOption { + entityId: Int! + displayName: String! + isRequired: Boolean! + isVariantOption: Boolean! +} +``` + +The following example shows how to get the first three product options associated with a product. In the response, all product options include queried fields from the `CatalogProductOption` interface, and those that are checkbox or datefields include additional fields. + + + + + ```graphql filename="Example query: Get product options for a product" showLineNumbers copy + # This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema#interfaces. + + query { + site { + product (entityId: 115) { + productOptions (first: 3) { + edges { + node { + + # fields that all product options include + entityId + displayName + isRequired + isVariantOption + + # additional fields for checkbox options + ... on CheckboxOption { + checkedByDefault + label + } + + # additional fields for datefield options + ... on DateFieldOption { + earliest + latest + limitDateBy + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get product options for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "productOptions": { + "edges": [ + { + "node": { + "entityId": 119, + "displayName": "Color", + "isRequired": true, + "isVariantOption": true + } + }, + { + "node": { + "entityId": 137, + "displayName": "Special feed", + "isRequired": false, + "isVariantOption": false, + "checkedByDefault": false, + "label": "YES" + } + }, + { + "node": { + "entityId": 138, + "displayName": "Custom date", + "isRequired": false, + "isVariantOption": false, + "earliest": "2022-10-27T06:00:00Z", + "latest": "2022-12-08T06:00:00Z", + "limitDateBy": "RANGE" + } + } + ] + } + } + } + } + } + ``` + + + +When you get product options, you can retrieve the available values, or product option values, for product options that are [multiple choice (Help Center)](https://support.bigcommerce.com/s/article/Product-Options-v3?language=en_US#mc). These values are made up of various types, swatch or radio buttons, for example. Each type of multiple choice value has a schema type that implements the `CatalogProductOptionValue` interface, meaning you can retrieve the common fields from `CatalogProductOptionValue` for any type of multiple choice value. + +```graphql filename="CatalogProductOptionValue interface" showLineNumbers copy +# Fields common among multiple choice values + +interface CatalogProductOptionValue { + entityId: Int! + label: String! + isDefault: Boolean!` +} +``` + +The following example shows a query that includes values for product options that are multiple choice. In the response, all product option values include queried fields from the `CatalogProductOptionValue` interface, and product option values that are swatch types include additional fields. The example query retrieves only the first product option and the first two values for that product option. + + + + + ```graphql filename="Example query: Get product options for a product" showLineNumbers copy + # This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema/#interfaces. + + query { + site { + product (entityId: 113) { + productOptions (first: 1) { + edges { + node { + + # fields that all product options include + entityId + displayName + isRequired + isVariantOption + + # additional fields for multiple choice options + ... on MultipleChoiceOption { + displayStyle + values (first: 2) { + edges { + node { + entityId + label + isDefault + + # additional fields for swatch options + ... on SwatchOptionValue { + hexColors + imageUrl (width: 2) + } + } + } + } + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get product options for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "productOptions": { + "edges": [ + { + "node": { + "displayStyle": "Swatch", + "entityId": 126, + "displayName": "Size", + "isRequired": true, + "isVariantOption": true, + "values": { + "edges": [ + { + "node": { + "hexColors": [ + "#912727", + "#D6A67C" + ], + "imageUrl": null, + "entityId": 129, + "label": "Small", + "isDefault": false + } + }, + { + "node": { + "hexColors": [ + "#46A754", + "#487790", + "#5645AF" + ], + "imageUrl": null, + "entityId": 130, + "label": "Medium", + "isDefault": true + } + } + ] + } + } + } + ] + } + } + } + } + } + ``` + + + + +## Get product images + +Query the images for products. Note that the default image is a thumbnail for the product. + +The following example retrieves the first two images and the default image for the specified product: + + + + + ```graphql filename="Example query: Get product images for a product" showLineNumbers copy + query { + site { + product (entityId: 113) { + images (first: 2) { + edges { + node { + url (width: 1) + urlOriginal + altText + isDefault + } + } + } + defaultImage { + url (width: 1) + urlOriginal + altText + isDefault + } + } + } + } + ``` + + + + + ```json filename="Example response: Get product images for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "images": { + "edges": [ + { + "node": { + "url": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/1w/products/113/379/IMAG0729__87810.1662649673.jpg", + "urlOriginal": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/original/products/113/379/IMAG0729__87810.1662649673.jpg", + "altText": "", + "isDefault": false + } + }, + { + "node": { + "url": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/1w/products/113/378/IMAG0724__62769.1662649673.jpg", + "urlOriginal": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/original/products/113/378/IMAG0724__62769.1662649673.jpg", + "altText": "", + "isDefault": true + } + } + ] + }, + "defaultImage": { + "url": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/1w/products/113/378/IMAG0724__62769.1662649673.jpg", + "urlOriginal": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/original/products/113/378/IMAG0724__62769.1662649673.jpg", + "altText": "", + "isDefault": true + } + } + } + } + } + ``` + + + +You can query product images at different resolutions. The following query retrieves the first image for the specified product at various resolutions: + + + + + ```graphql filename="Example query: Get product images at different resolutions" showLineNumbers copy + # This query retrieves four images. + # This query uses aliases. To learn more about aliases, see https://graphql.org/learn/queries/#aliases. + + query { + site { + product(entityId: 113) { + images (first: 1) { + edges { + node { + url320wide: url(width: 320) + url640wide: url(width: 640) + url960wide: url(width: 960) + url1280wide: url(width: 1280) + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get product images at different resolutions" showLineNumbers copy + { + "data": { + "site": { + "product": { + "images": { + "edges": [ + { + "node": { + "url320wide": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/320w/products/113/379/IMAG0729__87810.1662649673.jpg", + "url640wide": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/640w/products/113/379/IMAG0729__87810.1662649673.jpg", + "url960wide": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/960w/products/113/379/IMAG0729__87810.1662649673.jpg", + "url1280wide": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/1280w/products/113/379/IMAG0729__87810.1662649673.jpg" + } + } + ] + } + } + } + } + } + ``` + + + + +## Get product metafields + +Query product metafields by specifying the product metafield's namespace. The API returns only metafields that have storefront permissions. Permissions must be set to `write_and_sf_access` or `read_and_sf_access`. To set permissions, use the [Update a product metafield](/docs/rest-catalog/products/metafields#update-a-product-metafield) endpoint. + + + #### Product versus variant metafields + The query retrieves only **product** metafields. To retrieve **variant** metafields, see [Get variant metafields](/api-docs/storefront/graphql/variants#get-variant-metafields). + + +The following query retrieves the first two product metafields for the specified product: + + + + + ```graphql filename="Example query: Get product metafields for a product" showLineNumbers copy + query { + site { + product (entityId: 113) { + metafields (first: 2 namespace: "Warehouse Locations") { + edges { + node { + id + entityId + key + value + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get product metafields for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "metafields": { + "edges": [ + { + "node": { + "id": "TWV0YWZpZWxkczoxNQ==", + "entityId": 15, + "key": "Location", + "value": "4HG" + } + }, + { + "node": { + "id": "TWV0YWZpZWxkczoxNg==", + "entityId": 16, + "key": "Site", + "value": "2SL" + } + } + ] + } + } + } + } + } + ``` + + + +## Get product custom fields + +Query the custom fields for products. The following example retrieves the first two custom fields for the specified product: + + + + + ```graphql filename="Example query: Get custom fields for a product" showLineNumbers copy + query { + site { + product (entityId: 113) { + customFields (first: 2) { + edges { + node { + entityId + name + value + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get custom fields for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "customFields": { + "edges": [ + { + "node": { + "entityId": 4, + "name": "ISBN", + "value": "9876543210" + } + }, + { + "node": { + "entityId": 5, + "name": "Serial number", + "value": "1234567890" + } + } + ] + } + } + } + } + } + ``` + + + +## Get product gift wrapping options + +Query gift wrapping options that are available for a product. The following example retrieves the first two gift wrapping options for the specified product: + + + + + ```graphql filename="Example query: Get gift wrapping options for a product" showLineNumbers copy + query { + site { + product (entityId: 113) { + giftWrappingOptions (first: 2) { + edges { + node { + entityId + name + allowComments + previewImageUrl + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get gift wrapping options for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "giftWrappingOptions": { + "edges": [ + { + "node": { + "entityId": 1, + "name": "Christmas Wrapping", + "allowComments": false, + "previewImageUrl": "https://cdn11.bigcommerce.com/s-{store_hash}/product_images/wrap_images/christmas_1662668596__75551.jpg" + } + }, + { + "node": { + "entityId": 2, + "name": "Valentine's Day Wrapping", + "allowComments": true, + "previewImageUrl": null + } + } + ] + } + } + } + } + } + ``` + + + +## Get product reviews + +Query reviews for products. You retrieve only reviews that a merchant has approved. The following example retrieves the first review for the specified product: + + + + + ```graphql filename="Example query: Get reviews for a product" showLineNumbers copy + query { + site { + product (entityId: 113) { + reviews (first: 1) { + edges { + node { + entityId + author { + name + } + title + text + rating + createdAt { + utc + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get reviews for a product" showLineNumbers copy + { + "data": { + "site": { + "product": { + "reviews": { + "edges": [ + { + "node": { + "entityId": 3, + "author": { + "name": "example name" + }, + "title": "Excellent Flowers", + "text": "The best flowers for Valentine's Day. Would recommend.", + "rating": 4, + "createdAt": { + "utc": "2021-12-22T22:29:48Z" + } + } + } + ] + } + } + } + } + } + ``` + + + + +## Resources + +### GraphQL documentation +- [GraphQL Storefront API Overview](/api-docs/storefront/graphql/graphql-api-overview) +- [Guide to Working with Product Variants](/api-docs/storefront/graphql/variants) +- [GraphQL Storefront API Explorer](https://developer.bigcommerce.com/graphql-storefront/explorer) +- [GraphQL Storefront API Playground](https://developer.bigcommerce.com/graphql-storefront/playground) +- [GraphQL Language (graphql.org)](https://graphql.org/learn/queries) +- [GraphQL Schema and Types (graphql.org)](https://graphql.org/learn/schema) + +### REST API reference +- [Catalog API- Products](/docs/rest-catalog/products) overview +- [Catalog API- Product Options](/docs/rest-catalog/product-variant-options) overview +- [Catalog API- Update a product metafield](/docs/rest-catalog/products/metafields#update-a-product-metafield) endpoint +- [Catalog API- Get product metafields](/api-docs/storefront/graphql/products#get-product-metafields) endpoint +- [Catalog API- Get variant metafields](/api-docs/storefront/graphql/variants#get-variant-metafields) endpoint + +### Support articles +- [Product Options (Help Center)](https://support.bigcommerce.com/s/article/Product-Options-v3?language=en_US) diff --git a/docs/api-docs/storefront/graphql/graphql-variants.mdx b/docs/api-docs/storefront/graphql/graphql-variants.mdx new file mode 100644 index 000000000..9ba5c50eb --- /dev/null +++ b/docs/api-docs/storefront/graphql/graphql-variants.mdx @@ -0,0 +1,801 @@ +**GraphQL Storefront API** +# Guide to Working with Product Variants + +BigCommerce's GraphQL Storefront API lets frontend developers retrieve [variants](/docs/rest-catalog/product-variants) from a store. These built-in capabilities also allow developers to customize their hosted or headless storefronts with variant information. + +The GraphQL Storefront API lets you retrieve the following variant attributes and more: +- Price information in a store's transacting currency +- Variant options associated with a variant, along with their values +- Variant metafields that have storefront access + +You can access these attributes if a merchant makes the product visible on storefronts. + +This guide walks you through how to retrieve information for a variant. To retrieve information for the base product, see [Guide to Working with Products](/api-docs/storefront/graphql/products). For full schema documentation, see the [GraphQL Storefront Playground](https://developer.bigcommerce.com/graphql-storefront/playground). + +## Get a variant + +### Get a variant with the variants field + +Query a variant by specifying a variant identifier. For instance, use the variant `entityId` or `optionValueId` for the `variants` field as shown here: + + + + + ```graphql filename="Get a variant using the variant entity ID" showLineNumbers copy + # This example retrieves 1 variant. + # Specify multiple variant entityIds to retrieve multiple variants. + + query { + site { + product (entityId: 113) { + variants (entityIds: [98]) { + edges { + node { + # fields on the Variant object type + } + } + } + } + } + } + ``` + + + + + ```graphql filename="Get a variant using variant option values" showLineNumbers copy + # This query retrieves one variant. + # You must specify the entity ID for the value of each variant option. + + query { + site { + product (entityId: 113) { + variants (optionValueIds: [{optionEntityId: 116, valueEntityId: 108} {optionEntityId: 126, valueEntityId: 129}]) { + edges { + node { + # fields on the Variant object type + } + } + } + } + } + } + ``` + + ```graphql filename="Get a variant using variant option values" showLineNumbers copy + # This query retrieves two variants. + # For each variant, you must specify the entity ID for the value of each variant option. + # This query uses aliases and fragments. For more, see https://graphql.org/learn/queries. + + query { + site { + product (entityId: 113) { + v1: variants (optionValueIds: [{optionEntityId: 116, valueEntityId: 108} {optionEntityId: 126, valueEntityId: 129}]) { + edges { + node { + ...VariantFields + } + } + } + v2: variants (optionValueIds: [{optionEntityId: 116, valueEntityId: 109} {optionEntityId: 126, valueEntityId: 129}]){ + edges { + node { + ...VariantFields + } + } + } + } + } + } + + fragment VariantFields on Variant { + # fields on the Variant object type + } + ``` + + + + +Query all variants by omitting an argument for `variants`. + +### Get a variant with the product field + +Query a variant by specifying a variant identifier for the `product` field. Use the variant's entity ID, variant option value entity IDs, or variant SKU: + + + + + ```graphql filename="Get a variant using the variant entity ID" showLineNumbers copy + # This query retrieves one variant. + + query { + site { + product (variantEntityId: 27098) { + # fields on the Product object type + } + } + } + ``` + + + + + ```graphql filename="Get a variant using variant option values" showLineNumbers copy + # This query retrieves one variant. + # You must specify the entity ID for the value of each variant option. + + query { + site { + product ( + entityId: 113 + optionValueIds: [{optionEntityId: 116, valueEntityId: 108} {optionEntityId: 126, valueEntityId: 129}] + ) { + # fields on the Product object type + } + } + } + + ``` + + + + ```graphql filename="Get a variant using the variant sku" showLineNumbers copy + # This query retrieves one variant. + + query { + site { + product (sku: "variant-sku") { + # fields on the Product object type + } + } + } + ``` + + + + +Specifying a variant identifier for the `product` field returns variant information overlaid on the Product object. For example, if the variant has a different image, dimensions, SKU, or price, than the product, the variant's information will be returned. This allows you to directly query a variant. + +## Get variant identifiers + +Query identifying information for variants by using the following query: + + + + + ```graphql filename="Example query: Get basic information for a variant" showLineNumbers copy + query { + site { + product (entityId: 113) { + variants (entityIds: [127]) { + edges { + node { + id + entityId + sku + upc + mpn + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get basic information for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "id": "VmFyaWFudDoxMjc=", + "entityId": 127, + "sku": "ABC-1111-PI-SM-CO-RE", + "upc": "123346", + "mpn": "9876543210" + } + } + ] + } + } + } + } + } + ``` + + + +## Get variant prices and dimensions + +Query the prices and dimensions for variants. The following query retrieves prices and dimensions for the specified variant: + + + + + ```graphql filename="Example query: Get prices and dimensions for a variant" showLineNumbers copy + # This query uses fragments. For more, see https://graphql.org/learn/queries#fragments. + + query { + site { + product (entityId: 113) { + variants (entityIds: [98]) { + edges { + node { + prices { + price { + ...PriceFields + } + salePrice { + ...PriceFields + } + basePrice { + ...PriceFields + } + retailPrice { + ...PriceFields + } + } + width { + ...DimensionFields + } + height { + ...DimensionFields + } + depth { + ...DimensionFields + } + weight { + ...DimensionFields + } + } + } + } + } + } + } + + # fields on the Money object type + fragment PriceFields on Money { + value + currencyCode + } + + # fields on the Measurement object type + fragment DimensionFields on Measurement { + value + unit + } + ``` + + + + + ```json filename="Example response: Get prices and dimensions for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "prices": { + "price": { + "value": 4.5, + "currencyCode": "USD" + }, + "salePrice": { + "value": 5, + "currencyCode": "USD" + }, + "basePrice": { + "value": 10, + "currencyCode": "USD" + }, + "retailPrice": { + "value": 20, + "currencyCode": "USD" + } + }, + "width": { + "value": 2, + "unit": "in" + }, + "height": { + "value": 2, + "unit": "in" + }, + "depth": { + "value": 2, + "unit": "in" + }, + "weight": { + "value": 37, + "unit": "oz" + } + } + } + ] + } + } + } + } + } + ``` + + + +## Get variant options and variant option values + +Query variant options, and their associated values, that are available with variants. + +### Get variant options + +All variant options are [multiple choice (Help Center)](https://support.bigcommerce.com/s/article/Product-Options-v3?language=en_US#mc). + +The following example shows how to get the first two variant options that are associated with the base product for the specified variant: + + + + + ```graphql filename="Example query: Get variant options for a variant" showLineNumbers copy + # This query uses interfaces. For more, see https://graphql.org/learn/schema#interfaces. + + query { + site { + product (entityId: 113) { + variants (entityIds: [127]) { + edges { + node { + productOptions (first: 2) { + edges { + node { + ... on MultipleChoiceOption { + entityId + displayName + isRequired + isVariantOption + displayStyle + } + } + } + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get variant options for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "productOptions": { + "edges": [ + { + "node": { + "entityId": 116, + "displayName": "Color", + "isRequired": true, + "isVariantOption": true, + "displayStyle": "RadioButtons", + } + }, + { + "node": { + "entityId": 126, + "displayName": "Size", + "isRequired": true, + "isVariantOption": true, + "displayStyle": "Swatch", + } + } + ] + } + } + } + ] + } + } + } + } + } + ``` + + + +### Get variant option values + +All variant options are [multiple choice (Help Center)](https://support.bigcommerce.com/s/article/Product-Options-v3?language=en_US#mc). With variant options, you get to retrieve the multiple choice values, or the variant option values, associated with a variant. + +Multiple choice values are made up of various types, like swatch or radio buttons. Each type of multiple choice value has a specific schema that implements the `CatalogProductOptionValue` interface (meaning you can retrieve the common fields from `CatalogProductOptionValue` for any type of multiple choice value). For more on interfaces, see the [GraphQL Schema and Types- Interfaces](https://graphql.org/learn/schema#interfaces) documentation. + + +```graphql filename="CatalogProductOptionValue interface" showLineNumbers copy +# Fields common among multiple choice values + +interface CatalogProductOptionValue { + entityId: Int! + label: String! + isDefault: Boolean!` +} +``` + +The following example retrieves variant option values for the specified variant. In the response, all multiple choice values include queried fields from the `CatalogProductOptionValue` interface, and those that are swatch types include additional fields. The example query retrieves only the first two variant options associated with the base product. + + + + + ```graphql filename="Example query: Get variant option values for a variant" showLineNumbers copy + # This query uses interfaces. For more, see https://graphql.org/learn/schema#interfaces. + + query { + site { + product (entityId: 113) { + variants (entityIds: [127]) { + edges { + node { + productOptions (first: 2) { + edges { + node { + + # fields all muliple choice options include + ... on MultipleChoiceOption { + values { + edges { + node { + entityId + label + isDefault + + # additional fields for swatch options + ... on SwatchOptionValue { + hexColors + imageUrl (width: 2) + } + } + } + } + } + } + } + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get variant option values for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "productOptions": { + "edges": [ + { + "node": { + "values": { + "edges": [ + { + "node": { + "entityId": 108, + "label": "Pink", + "isDefault": true + } + } + ] + } + } + }, + { + "node": { + "values": { + "edges": [ + { + "node": { + "entityId": 129, + "label": "Small", + "isDefault": false, + "hexColors": [ + "#912727", + "#D6A67C" + ], + "imageUrl": null + } + } + ] + } + } + } + ] + } + } + } + ] + } + } + } + } + } + ``` + + + +Retrieve variant option values using the `options` field. The following query retrieves the variant option values that are associated with the specified variant. The example query retrieves only the first two variant options associated with the base product. + + + + + ```graphql filename="Example query: Get variant option values for a variant" showLineNumbers copy + query { + site { + product(entityId: 113) { + variants(entityIds: [127]) { + edges { + node { + options (first: 2) { + edges { + node { + entityId + displayName + isRequired + values { + edges { + node { + entityId + label + } + } + } + } + } + } + } + } + } + } + } + } + + ``` + + + + + ```json filename="Example response: Get variant option values for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "options": { + "edges": [ + { + "node": { + "entityId": 116, + "displayName": "Color", + "isRequired": true, + "values": { + "edges": [ + { + "node": { + "entityId": 108, + "label": "Pink" + } + } + ] + } + } + }, + { + "node": { + "entityId": 126, + "displayName": "Size", + "isRequired": true, + "values": { + "edges": [ + { + "node": { + "entityId": 129, + "label": "Small" + } + } + ] + } + } + } + ] + } + } + } + ] + } + } + } + } + } + ``` + + + +## Get variant images + +Query the images for variants. The following query retrieves the image for the specified variant: + + + + + ```graphql filename="Example query: Get images for a variant" showLineNumbers copy + query { + site { + product (entityId: 113) { + variants (entityIds: [127]) { + edges { + node { + defaultImage { + url (width: 1) + urlOriginal + altText + isDefault + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get images for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "defaultImage": { + "url": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/1w/attribute_rule_images/32_source_1667245516.png", + "urlOriginal": "https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/original/attribute_rule_images/32_source_1667245516.png", + "altText": "", + "isDefault": true + } + } + } + ] + } + } + } + } + } + ``` + + + +## Get variant metafields + +Query variant metafields by specifying the namespace for the variant metafields. The API returns only metafields that have storefront permissions. Permissions must be set to `write_and_sf_access` or `read_and_sf_access`. To set permissions, use the [Update product variant metafields](/docs/rest-catalog/product-variants/metafields#update-product-variant-metafields) endpoint. + + + #### Variant versus product metafields + The query returns only **variant** metafields. To retrieve **product** metafields, see [Get product metafields](/api-docs/storefront/graphql/products#get-product-metafields). + + +The following query retrieves the first variant metafield for the specified variant: + + + + + ```graphql filename="Example query: Get variant metafields for a variant" showLineNumbers copy + query { + site { + product (entityId: 113) { + variants (entityIds: [127]) { + edges { + node { + metafields (first: 1 namespace: "Warehouse Locations") { + edges { + node { + id + entityId + key + value + } + } + } + } + } + } + } + } + } + ``` + + + + + ```json filename="Example response: Get variant metafields for a variant" showLineNumbers copy + { + "data": { + "site": { + "product": { + "variants": { + "edges": [ + { + "node": { + "metafields": { + "edges": [ + { + "node": { + "id": "TWV0YWZpZWxkczoxOA==", + "entityId": 18, + "key": "Site number", + "value": "3TZ" + } + } + ] + } + } + } + ] + } + } + } + } + } + ``` + + + +## Resources + +### GraphQL documentation +- [GraphQL Storefront API Overview](/api-docs/storefront/graphql/graphql-api-overview) +- [Guide to Working with Products](/api-docs/storefront/graphql/products) +- [GraphQL Storefront API Explorer](https://developer.bigcommerce.com/graphql-storefront/explorer) +- [GraphQL Storefront API Playground](https://developer.bigcommerce.com/graphql-storefront/playground) +- [GraphQL Language (graphql.org)](https://graphql.org/learn/queries) +- [GraphQL Schema and Types (graphql.org)](https://graphql.org/learn/schema) + +### REST API endpoints +- [Catalog API- Variants](/docs/rest-catalog/product-variants) overview +- [Catalog API- Update product variant metafields](/docs/rest-catalog/product-variants/metafields#update-product-variant-metafields) endpoint +- [Catalog API- Get variant metafields](/api-docs/storefront/graphql/variants#get-variant-metafields) endpoint +- [Catalog API- Get product metafields](/api-docs/storefront/graphql/products#get-product-metafields) endpoint + +### Support articles +- [Product Options (Help Center)](https://support.bigcommerce.com/s/article/Product-Options-v3?language=en_US)