Skip to main content
Version: 2.11

Querying Product Information

Introduction#

This guide describes how to obtain products from the Saleor GraphQL API.

You can either retrieve a single product or a list of products. You may require a list of products in many situations, for example, when you need to simply display the catalog in your storefront, or to provide a third party service with a list of products available in your store.

Retrieving a list of products#

To fetch a product list, you need to run the products query. The products field is a paginated collection, see Pagination for more information.

Let's take a look at an example query to fetch a list of products:

{  products(first: 2) {    edges {      node {        id        name      }    }  }}

Response:

{  "data": {    "products": {      "edges": [        {          "node": {            "id": "UHJvZHVjdDo3Mg==",            "name": "Apple Juice"          }        },        {          "node": {            "id": "UHJvZHVjdDo3NA==",            "name": "Banana Juice"          }        }      ]    }  }}

In this example, for each product, we want to return the following fields:

  • id: the unique product ID, most operations will require one.
  • name: the name of the product.

Filtering#

The products query gives the ability to filter the results. Use the optional filter argument. Some of the filters that are available here are:

  • search: String: search by name or part of the description.
  • price: ...: filter by base price:
    • price: {lte: Float}: price lower than or equal to given value.
    • price: {gte: Float}: price greater than or equal to given value.
  • minimalPrice: ...: filter by minimal variant price:
    • minimalPrice: {lte: Float}: price lower than or equal to given value.
    • minimalPrice: {gte: Float}: price greater than or equal to given value.
  • stockAvailability: ...: filter by available stock:
    • stockAvailability: IN_STOCK: only available products.
    • stockAvailability: OUT_OF_STOCK: only out-of-stock products.

Here is an example query that looks for the first 3 products containing the term "juice" in the title or description:

{  products(first: 3, filter: { search: "juice" }) {    edges {      node {        name      }    }  }}

Response:

{  "data": {    "products": {      "edges": [        {          "node": {            "name": "Apple Juice"          }        },        {          "node": {            "name": "Banana Juice"          }        },        {          "node": {            "name": "Bean Juice"          }        }      ]    }  }}

Sorting#

In products you can also sort the results using two sortBy arguments:

  • field: the field to use for sorting the results from several predefined choices:
    • DATE: sort products by last update.
    • MINIMAL_PRICE: sort products by minimal variant price.
    • NAME: sort products by name.
    • PRICE: sort products by base price.
    • PUBLICATION_DATE: sort products by publication date.
    • PUBLISHED: sort products by publication status.
    • TYPE: sort products by product type.
  • direction: The direction for sorting items:
    • ASC: sort ascending.
    • DESC: sort descending.

This example shows how to sort the products list by the minimal variant price, lowest to highest:

{  products(    first: 2    sortBy: { field: MINIMAL_PRICE, direction: ASC }  ) {    edges {      node {        name        minimalVariantPrice {          amount          currency        }      }    }  }}

Response:

{  "data": {    "products": {      "edges": [        {          "node": {            "name": "Blue Hoodie",            "minimalVariantPrice": {              "amount": 2.5,              "currency": "USD"            }          }        },        {          "node": {            "name": "Banana Juice",            "minimalVariantPrice": {              "amount": 3,              "currency": "USD"            }          }        }      ]    }  }}

Retrieving a single product#

To get a single product, use the product query, which requires only one input field:

  • id: the unique product ID.

Here is the example query that fetches a single product:

query {  product(id: "UHJvZHVjdDoxMTU=") {    id    name  }}

Retrieving product variants#

To obtain product variants, query the variants field on the Product type:

{  products(first: 1) {    edges {      node {        id        name        variants {          id          name        }      }    }  }}

Response:

{  "data": {    "products": {      "edges": [        {          "node": {            "id": "UHJvZHVjdDo3Mg==",            "name": "Apple Juice",            "variants": [              {                "id": "UHJvZHVjdFZhcmlhbnQ6MjAz",                "name": "1l"              },              {                "id": "UHJvZHVjdFZhcmlhbnQ6MjA0",                "name": "2l"              },              {                "id": "UHJvZHVjdFZhcmlhbnQ6MjAy",                "name": "500ml"              }            ]          }        }      ]    }  }}

Like products, here we're asking for two fields from each variant:

  • id: the unique variant ID.
  • name: the name of the variant.

Pricing#

Use the pricing field of products and variants to obtain pricing information.

Here are the available fields for product pricing:

type ProductPricingInfo {  priceRange: TaxedMoneyRange  priceRangeUndiscounted: TaxedMoneyRange  discount: TaxedMoney  onSale: Boolean}

And similar fields for product variants:

type VariantPricingInfo {  price: TaxedMoney  priceUndiscounted: TaxedMoney  discount: TaxedMoney  onSale: Boolean}

The main difference is that products don't have a price point, instead they offer a price range that includes all of their variant prices.

Here are the money types returned by the above:

type TaxedMoneyRange {  # lowest price  start: TaxedMoney  # highest price  stop: TaxedMoney}
type TaxedMoney {  # before tax  net: Money!  # after tax  gross: Money!
  # gross - net  tax: Money!  # repeated for convenience  currency: String!}
type Money {  amount: Float!  currency: String!}

Images#

The Product type contains two fields that refer to its images:

  • thumbnail: the product's main image. An optional size parameter specifies the desired size in pixels if given. The following fields are available:
    • url: the image's URL.
    • alt: the alternative text to include when displaying the image.
  • images: gives you access to the entire list of associated product images with the following fields available:
    • url: the image's URL. An optional size parameter specifies the desired size in pixels if given.
    • alt: the alternative text to include when displaying the image.

Here's a query that asks for both the thumbnail and all images of the first product, optimized for display at 100×100px:

{  products(first: 1) {    edges {      node {        id        name        thumbnail(size: 100) {          url          alt        }        images {          url(size: 100)          alt        }      }    }  }}

Response:

{  "data": {    "products": {      "edges": [        {          "node": {            "id": "UHJvZHVjdDo3Mg==",            "name": "Apple Juice",            "thumbnail": {              "url": "https://demo.saleor.io/media/__sized__/products/saleordemoproduct_fd_juice_06-thumbnail-120x120.png",              "alt": ""            },            "images": [              {                "url": "https://demo.saleor.io/media/__sized__/products/saleordemoproduct_fd_juice_06-thumbnail-120x120.png",                "alt": ""              }            ]          }        }      ]    }  }}

Examples#

Here's a more complex GraphQL query that combines all of the above information:

{  products(first: 2, sortBy: {field: NAME}) {    edges {      node {        id        name        pricing {          priceRange {            start {              gross {                amount                currency              }            }          }          discount {            gross {              amount              currency            }          }          priceRangeUndiscounted {            start {              gross {                amount                currency              }            }          }        }        thumbnail {          url        }      }    }  }}