Skip to main content

Getting started with querying products and collections

The Storefront API lets you build custom storefronts with any language and technology. It provides public access using GraphQL to products, collections, customers, carts, checkouts, and other store resources that you can use to build custom purchasing experiences. After you've requested access tokens for your app and generated a Storefront API access token, you can make queries using the Storefront API.


After you've finished this tutorial, you'll have accomplished the following:

  • Requested public, unauthenticated Storefront API access scopes for your app
  • Generated a Storefront API access token
  • Queried products and collections
Tip

If you're a Shopify Partner, then you can create a development store to test Storefront API queries.



You can use the products query to retrieve a list of products. The products query uses an argument (for example, first) to specify the number of results to query.

The following example shows how to query the IDs of the first 5 products in your store. For more information on selecting which set of results to query, refer to Paginating results with GraphQL.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
products(first:5) {
edges {
node {
id
}
}
}
}

JSON response

{
"data": {
"products": {
"edges": [
{
"node": {
"id": "gid:\/\/shopify\/Product\/1"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/2"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/3"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/4"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/5"
}
}
]
}
}
}

Anchor to Query a single productQuery a single product

Products are identified by a globally unique ID, which can be used to query for information. You can use the product query to retrieve a single product. The following example shows how to pass in the product ID to the product query.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
# You can use `product(handle:)` to query a single product by its handle instead.
product(id: "gid:\/\/shopify\/Product\/1") {
title
}
}

JSON response

{
"data": {
"product": {
"title": "Black Ban Glasses"
}
}
}

Anchor to Query product variantsQuery product variants

A product variant represents a different version of a product, such as differing sizes or differing colors. You can query the variants associated with a product by querying variants on the Product object.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
node(id: "gid:\/\/shopify\/Product\/1") {
id
... on Product {
variants(first: 5) {
edges {
node {
id
}
}
}
}
}
}

JSON response

{
"data": {
"node": {
"id": "gid:\/\/shopify\/Product\/1",
"variants": {
"edges": [
{
"node": {
"id": "gid:\/\/shopify\/ProductVariant\/1"
}
},
{
"node": {
"id": "gid:\/\/shopify\/ProductVariant\/2"
}
},
{
"node": {
"id": "gid:\/\/shopify\/ProductVariant\/3"
}
},
{
"node": {
"id": "gid:\/\/shopify\/ProductVariant\/4"
}
},
{
"node": {
"id": "gid:\/\/shopify\/ProductVariant\/5"
}
}
]
}
}
}
}

Anchor to Query product recommendationsQuery product recommendations

Product recommendations can help merchants boost sales and conversions. You can use the productRecommendations query to retrieve a list of up to ten recommended products that display to customers. In your query, provide the following arguments:

  • productId: The global ID of the product that's published to the storefront. This is the product for which the recommended products are generated.
  • intent: The type of recommendation set that will be generated. This helps you tailor recommendations for a particular surface on a storefront or selling strategy. For more information, refer to recommendation intents.

The following example shows how to retrieve related product recommendations for a given product. The query returns the product IDs for each recommended product.

Note

Shopify provides auto-generated product recommendations. Merchants can also customize their product recommendations using the Shopify Search & Discovery app.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
# The `intent` argument is available only in the unstable API version.
productRecommendations(productId: "gid://shopify/Product/1", intent: RELATED) {
id
}
}

JSON response

{
"data": {
"productRecommendations": [
{
"id": "gid:\/\/shopify\/Product\/2"
},
{
"id": "gid:\/\/shopify\/Product\/3"
},
{
"id": "gid:\/\/shopify\/Product\/4"
},
{
"id": "gid:\/\/shopify\/Product\/5"
},
{
"id": "gid:\/\/shopify\/Product\/6"
},
{
"id": "gid:\/\/shopify\/Product\/7"
},
{
"id": "gid:\/\/shopify\/Product\/8"
},
{
"id": "gid:\/\/shopify\/Product\/9"
},
{
"id": "gid:\/\/shopify\/Product\/10"
},
{
"id": "gid:\/\/shopify\/Product\/11"
}
]
}
}

You can use the Storefront API to query a product's media and display it on a storefront.

Specify the media field on the Product object to query for a product's media. Then use a fragment to specify the fields that you want to return for each possible media type.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
product(id: "gid:\/\/shopify\/ProductVariant\/1") {
id
media(first: 10) {
edges {
node {
mediaContentType
alt
...mediaFieldsByType
}
}
}
}
}
fragment mediaFieldsByType on Media {
...on ExternalVideo {
id
embeddedUrl
}
...on MediaImage {
image {
url
}
}
...on Model3d {
sources {
url
mimeType
format
filesize
}
}
...on Video {
sources {
url
mimeType
format
height
width
}
}
}

JSON response

{
"data": {
"product": {
"id": "gid:\/\/shopify\/ProductVariant\/1",
"media": {
"edges": [
{
"node": {
"mediaContentType": "VIDEO",
"alt": "Comparison video showing the different models of watches.",
"sources": [
{
"url": "https://videos.shopifycdn.com/c/vp/2a82811738ca41e7a508e6744028d169/SD-360p.mp4?Expires=1575744400&KeyName=core-signing-key-1&Signature=OPKELzhY-kYTx9QH9x6NJA9IqnI=",
"mimeType": "video/mp4",
"format": "mp4",
"height": 360,
"width": 640
}
]
}
},
{
"node": {
"mediaContentType": "IMAGE",
"alt": "Polaris watch",
"image": {
"url": "https://cdn.shopify.com/s/files/1/1768/1717/products/IGQ.png?v=1560528103"
}
}
}
]
}
}
}
}

A collection represents a grouping of products that a store owner can create to organize them or make their stores easier to browse. For example, a merchant might create a collection for a specific type of product that they sell, such as footwear.

Merchants can create collections by selecting products individually or by defining rules that automatically determine whether products are included.

The following example shows how to query for collections and the products that belong to those collections.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
collections(first: 2) {
edges {
node {
id
products(first: 5) {
edges {
node {
id
}
}
}
}
}
}
}

JSON response

{
"data": {
"collections": {
"edges": [
{
"node": {
"id": "gid:\/\/shopify\/Collection\/1",
"products": {
"edges": [
{
"node": {
"id": "gid:\/\/shopify\/Product\/1"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/2"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/3"
}
}
]
}
}
},
{
"node": {
"id": "gid:\/\/shopify\/Collection\/2",
"products": {
"edges": [
{
"node": {
"id": "gid:\/\/shopify\/Product\/4"
}
},
{
"node": {
"id": "gid:\/\/shopify\/Product\/5"
}
}
]
}
}
}
]
}
}
}


Was this page helpful?