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 optionalsize
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 optionalsize
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
}
}
}
}
}