ProductsQuery

Description

Retrieves a list of products based on specified criteria. This query allows you to fetch multiple products with filtering, sorting, and pagination options.

Endpoint

query products($handle: [QueryArgument], $yuiId: [QueryArgument], $price: [QueryArgument], $type: [String]) {
  products(handle: $handle, yuiId: $yuiId, price: $price, type: $type) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
handle	[QueryArgument]	No	Narrows the query results based on the handle on the product.
yuiId	[QueryArgument]	No	Narrows the query results based on the YUI ID on the product.
price	[QueryArgument]	No	Narrows the query results based on the price on the product.
price_incl_tax	[QueryArgument]	No	Narrows the query results based on the price including tax on the product.
price_excl_tax	[QueryArgument]	No	Narrows the query results based on the price excluding tax on the product.
specialPrice	[QueryArgument]	No	Narrows the query results based on the special price on the product.
special_price_incl_tax	[QueryArgument]	No	Narrows the query results based on the special price including tax on the product.
special_price_excl_tax	[QueryArgument]	No	Narrows the query results based on the special price excluding tax on the product.
type	[String]	No	Narrows the query results based on the product type the products belong to per the product type's handles.

Common Element Arguments

In addition to the specific arguments above, this query also supports common element arguments:

Argument	Type	Required	Description
id	[QueryArgument]	No	Narrows the query results based on the element's ID.
uid	[String]	No	Narrows the query results based on the element's UID.
status	[String]	No	Narrows the query results based on the element's status.
title	[String]	No	Narrows the query results based on the element's title.
slug	[String]	No	Narrows the query results based on the element's slug.
limit	Int	No	Sets the limit for paginated results.
offset	Int	No	Sets the offset for paginated results.
orderBy	String	No	Sets the field to order results by.
siteId	Int	No	Determines which site to fetch results from.

Return Values

The query returns an array of Product objects with the following fields:

Field	Type	Description
id	ID	The unique identifier for the product.
title	String	The title of the product.
handle	String	The handle of the product.
yuiId	String	The YUI ID of the product.
price	Float	The base price of the product.
price_incl_tax	Float	The price including tax of the product.
price_excl_tax	Float	The price excluding tax of the product.
specialPrice	Float	The special price of the product, if applicable.
special_price_incl_tax	Float	The special price including tax of the product, if applicable.
special_price_excl_tax	Float	The special price excluding tax of the product, if applicable.
type	String	The type of the product.
url	String	The URL of the product.
...	...	Additional fields depending on the product type.

Usage Example

query {
  products(limit: 10, type: ["simple"], price: [">", 10]) {
    id
    title
    handle
    price
    price_incl_tax
    url
  }
}

Example Response

{
  "data": {
    "products": [
      {
        "id": "123",
        "title": "Sample Product 1",
        "handle": "sample-product-1",
        "price": 19.99,
        "price_incl_tax": 23.99,
        "url": "/products/sample-product-1"
      },
      {
        "id": "124",
        "title": "Sample Product 2",
        "handle": "sample-product-2",
        "price": 29.99,
        "price_incl_tax": 35.99,
        "url": "/products/sample-product-2"
      }
    ]
  }
}

Notes

• The QueryArgument type allows for various comparison operators. For example, you can use price: [">", 10] to find products with a price greater than 10.
• You can combine multiple arguments to narrow down the results further.
• The limit and offset arguments can be used for pagination.
• The orderBy argument can be used to sort the results by a specific field.
• The available fields in the response depend on the product type and may include custom fields defined in your product types.