Getting started with the Storefront API

The Storefront API provides unauthenticated access to products, collections, customers, checkouts, and other store resources that you can use to build custom purchasing experiences.

This tutorial shows you how to accomplish some common tasks with the Storefront API.

Requirements

  • You've created a development store.

  • You've authenticated using basic HTTP authentication for your private app or using OAuth for your public or custom app. If you're authenticating to the Storefront API as a public app, then you need to turn your app into a sales channel.

    The following example URL shows how you request unauthenticated scopes during OAuth:

    https://{shop}.myshopify.com/admin/oauth/authorize?client_id={client_id}&scope=unauthenticated_read_product_listings,unauthenticated_write_checkouts,unauthenticated_write_customers,unauthenticated_read_customer_tags,unauthenticated_read_content,unauthenticated_read_product_tags&redirect_uri=https://www.google.com/&state=nonce1

  • You've obtained a Storefront API access token and included it in your request header:

    X-Shopify-Storefront-Access-Token: {storefront-access-token}

  • You've created products, product variants, and collections in your store.

1. Retrieve products

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

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

Query: POST /api/2021-04/graphql.json

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

View response

JSON response

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ2NDUwMTQ="
          }
        },
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ3MTA1NTA="
          }
        },
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTgxNTkwMDc3NjY="
          }
        },
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU1OTE0ODQ4NTgzOTA="
          }
        },
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU2MDY3MTA2NzM0MzA="
          }
        }
      ]
    }
  }
}

2. Retrieve a single product

Products are identified by a globally unique ID, which can be used to query for information. To retrieve a single product, you can start at the node query root and provide the product ID.

Query: POST /api/2021-04/graphql.json

{
  node(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU2MDY3MTA2NzM0MzA=") {
    id
    ... on Product {
      title
    }
  }
}

View response

JSON response

{
  "data": {
    "node": {
      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU2MDY3MTA2NzM0MzA=",
      "title": "Black Ban Glasses"
    }
  }
}

3. Retrieve product variants

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

Query: POST /api/2021-04/graphql.json

{
  node(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ3MTA1NTA=") {
    id
    ... on Product {
      variants(first: 5) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
}

View response

JSON response

{
  "data": {
    "node": {
      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ3MTA1NTA=",
      "variants": {
        "edges": [
          {
            "node": {
              "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zMTM2NTgxODc0NDg1NA=="
            }
          },
          {
            "node": {
              "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zMTM3MzI0OTk3MDE5OA=="
            }
          },
          {
            "node": {
              "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zMTM3Mzk3Nzg3ODU1MA=="
            }
          },
          {
            "node": {
              "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zMTM3NDEwOTgwMjUxOA=="
            }
          },
          {
            "node": {
              "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zMTM3NDgzNTk3NDE2Ng=="
            }
          }
        ]
      }
    }
  }
}

4. Retrieve product media

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

Specify the media field on the Product type 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.

Query: POST /api/2021-04/graphql.json

{
  node(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ3MTA1NTA=") {
    ...on Product {
      id
        media(first: 10) {
        edges {
          node {
            mediaContentType
            alt
            ...mediaFieldsByType
          }
        }
      }
    }
  }
}

fragment mediaFieldsByType on Media {
  ...on ExternalVideo {
    id
    embeddedUrl
  }
  ...on MediaImage {
    image {
      originalSrc
    }
  }
  ...on Model3d {
    sources {
      url
      mimeType
      format
      filesize
    }
  }
  ...on Video {
    sources {
      url
      mimeType
      format
      height
      width
    }
  }
}

View response

JSON response

{
  "data": {
    "node": {
      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ3MTA1NTA=",
      "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": {
                "originalSrc": "https://cdn.shopify.com/s/files/1/1768/1717/products/IGQ.png?v=1560528103"
              }
            }
          }
        ]
      }
    }
  }
}

5. Retrieve collections

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.

Query: POST /api/2021-04/graphql.json

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

View response

JSON response

{
  "data": {
    "collections": {
      "edges": [
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzI2MTM5NzI1MDA3MA==",
            "products": {
              "edges": [
                {
                  "node": {
                    "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzY1NDExNTM4NjE2NTQ="
                  }
                },
                {
                  "node": {
                    "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTgxNTkwMDc3NjY="
                  }
                },
                {
                  "node": {
                    "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU1OTE0ODQ4NTgzOTA="
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "id": "Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzI2MTM5NzI4MjgzOA==",
            "products": {
              "edges": [
                {
                  "node": {
                    "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzQzNTM1NTQ3MTA1NTA="
                  }
                },
                {
                  "node": {
                    "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU1OTE0ODQ4NTgzOTA="
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Next steps

  • Visit our storefront-api-examples project on GitHub to access example apps built with a variety of open-source libraries.
  • Learn about the different tools you can use to create unique buying experiences anywhere your customers are, including websites, apps, and video games.

On this page