Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 55 ยท Admin GraphQL API

Querying Products and Variants

Learn to read products, variants, options and media with the Shopify Admin GraphQL API, use the search query syntax, and build safe queries with runnable stand-ins.

Products are the first thing most apps read. A catalog sync, a bulk editor, a pricing tool and an inventory alert all start with the same question: which products exist, and what do their variants look like? The Admin GraphQL API answers it with the products connection, and the shape of that answer is worth learning well, because variants, options and media follow the same patterns as everything else in the API.

This lesson shows how to select the fields you need, how variants and options relate, how to filter with Shopify's search syntax, and how to keep the cost low. All requests target Admin API version 2026-07 and need the read_products access scope (see Managed Installation and Access Scopes). If the vocabulary of queries, variables and global IDs is new, read GraphQL for Shopify Developers first.

Real requests to a shop cannot run on this site, so the GraphQL documents below are read-only. The runnable examples are stand-ins: a small query builder and a walkthrough over a hand-written mock response. They show the shape of the data, not live Shopify behavior.

The shape of a product

A product is the thing a customer thinks they are buying ("Linen shirt"). A variant is one purchasable combination of that product ("Linen shirt, blue, medium"), and it is the variant that carries a price, a SKU and an inventory item. Every product has at least one variant, even products that offer no choices (Shopify creates a hidden "Default Title" variant). For the commerce theory behind this split, see Variants and Options.

Options describe the choices. A product with options Color (blue, green) and Size (S, M) has up to four variants, each with selectedOptions that tell you which combination it is.

Here is a typical read-only query:

GRAPHQL
query FirstProducts {
  products(first: 5) {
    nodes {
      id
      title
      handle
      status
      vendor
      productType
      tags
      totalInventory
      options {
        name
        values
      }
      variants(first: 10) {
        nodes {
          id
          title
          sku
          price
          selectedOptions {
            name
            value
          }
        }
      }
      featuredMedia {
        preview {
          image {
            url
            altText
          }
        }
      }
    }
  }
}

A few details are worth noting:

  • id is a global ID such as gid://shopify/Product/1234567890. Pass it back unchanged when you update or delete.
  • status is an enum: ACTIVE, DRAFT or ARCHIVED. Drafts and archived products are not visible on the storefront, but the Admin API returns them.
  • price on a variant is a decimal string such as "29.00", not a number. Convert it carefully, as explained in Money as Integers.
  • totalInventory is the sum across all locations for tracked variants. Per-location numbers live on the inventory item, which a later project covers in Project: Low-Stock Alerts App.
  • Fields on Product such as descriptionHtml, createdAt and updatedAt are available too. Select only what you use.

Nodes or edges

Connections give you two ways to read a list. nodes returns the objects directly. edges wraps each object together with its cursor. When you only need the data, use nodes; when you need the cursor of each item, use edges. The next lesson, Pagination with Cursors, explains when each is useful.

Variables instead of string building

In real code you do not paste values into the query text. You send a fixed document and a separate variables object. This keeps queries cacheable, prevents injection mistakes and makes logs readable.

GRAPHQL
query Products($first: Int!, $search: String) {
  products(first: $first, query: $search, sortKey: UPDATED_AT, reverse: true) {
    nodes {
      id
      title
      status
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
JSON
{ "first": 25, "search": "status:active AND vendor:Acme" }

The request goes to https://{shop}.myshopify.com/admin/api/2026-07/graphql.json with the header X-Shopify-Access-Token. The version in that URL is covered in API Versioning and Deprecations.

The search query syntax

The query argument takes a search string, not GraphQL. It is a small filter language that Shopify evaluates on the server, and it is much cheaper than downloading everything and filtering in your app. A term is field:value. Terms are combined with AND, OR and NOT (or a leading -), and parentheses group them. These fields are widely used on products:

Search term Matches
status:active products with that status
vendor:Acme products from that vendor (quote values with spaces: vendor:'Blue Ridge')
product_type:shirt products with that product type
tag:sale products carrying that tag
title:*linen* titles matching a wildcard
sku:LIN-100 products with a variant with that SKU
inventory_total:<5 low total inventory (comparison operators <, >, <=, >=)
created_at:>2026-01-01 products created after a date
updated_at:>2026-06-01 products changed recently, ideal for incremental syncs

An example: (tag:sale OR tag:clearance) AND status:active AND -vendor:Acme means active products tagged sale or clearance, excluding one vendor. The list of searchable fields differs per object and can grow, so check the documentation for the version you target. An invalid field is usually ignored or reported rather than breaking your whole query, so test searches against a development store.

Node.js A small product search builder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The builder is plain string handling, but it captures the habit that matters: build the search string from parts, and let one helper decide how values are quoted. Never concatenate untrusted input into a search string without that step, because a stray quote can change what the filter means.

Variants, options and the 'more than the page' problem

A connection inside a connection multiplies cost, as you saw in Rate Limits and Query Cost. products(first: 50) with variants(first: 100) asks for up to 5,000 variants in one request. Two good habits keep this under control:

  1. Ask for a small number of variants in the product query (first: 10 is plenty for a product list view).
  2. When you need all variants of one product, query that product by ID and paginate its variants connection on its own.
GRAPHQL
query OneProduct($id: ID!, $after: String) {
  product(id: $id) {
    title
    variants(first: 100, after: $after) {
      nodes {
        id
        sku
        price
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

You can also fetch a single variant with productVariant(id:), or look up a product by handle with productByHandle (check the current documentation for the recommended handle lookup in your version). For anything that scans the whole catalog, such as a nightly export, use Bulk Operations instead of paging thousands of times.

Media

Images and videos hang off the product's media connection (and featuredMedia for the main one). Because media is a union of types (images, videos, 3D models, external video), you use inline fragments to read type-specific fields:

GRAPHQL
media(first: 5) {
  nodes {
    mediaContentType
    alt
    ... on MediaImage {
      image {
        url
        width
        height
      }
    }
  }
}

The image.url is a CDN address. You can request resized versions through the URL transform arguments documented for images, so you rarely need to download originals.

Walking through a response

A response mirrors your query: the same names, the same nesting. The runnable example below takes a mock response written by hand and flattens it into rows, which is exactly what a catalog sync does before it writes to its own database. It also shows the usual defensive checks.

Node.js Flatten a mock products response

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice three things the code handles on purpose: a missing SKU (null or an empty string is allowed in Shopify), the draft product that the API returns anyway, and the price conversion that avoids floating point. Real catalog code needs all three.

Common mistakes

  • Treating price as a number. It is a string; convert it with care.
  • Forgetting that variants are paginated too. The default page is small, and a product with many variants will be cut off silently unless you check pageInfo.
  • Filtering in your app. Send the filter in query so Shopify does the work and you pay for fewer objects.
  • Hard-coding the numeric ID format. Keep the full gid:// string as the identifier; extract the number only for display or for your own database keys.
  • Reading more than you need. Each nested field is a cost line. Query the fields your screen or job actually uses.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which object carries the price and SKU of something a customer can buy?

    A product is the catalog entry; each purchasable combination is a variant, and the variant holds price, SKU and the link to inventory. Options only describe the choices.
  2. 2. What type does a variant's price field have in the Admin GraphQL API?

    Money amounts are returned as decimal strings so no precision is lost. Convert to integer cents before doing arithmetic.
  3. 3. You want only active products tagged sale. Where should that filter live?

    The search string is evaluated by Shopify, so you transfer and pay for only the matching products.
  4. 4. Why is a products(first: 50) query with variants(first: 100) inside risky?

    Inner connections are counted once per outer object, so cost multiplies. Use a small inner page, or query one product's variants separately.

Summary

  • Products hold shared data; variants are the purchasable combinations with price, SKU and inventory, and selectedOptions tells you which combination each one is.
  • Use nodes when you want data and edges when you also need each cursor; always read pageInfo for lists that can be longer than one page.
  • Send variables separately from the query text and build the query search string with a helper that quotes values.
  • The search syntax (status:, vendor:, tag:, inventory_total:<5, updated_at:>) filters on Shopify's side and saves cost.
  • Prices are decimal strings, IDs are global IDs, SKUs can be empty, and drafts are returned by the API.
  • Keep nested connections small and use bulk operations for whole-catalog jobs.

Next: Pagination with Cursors.