Choose a version:

productVariants

query

Retrieves a list of product variants associated with a product.

A product variant is a specific version of a product that comes in more than one option, such as size or color. For example, if a merchant sells t-shirts with options for size and color, then a small, blue t-shirt would be one product variant and a large, blue t-shirt would be another.

Use the productVariants query when you need to:

Search for product variants by attributes such as SKU, barcode, or inventory quantity.
Filter product variants by attributes, such as whether they're gift cards or have custom metafields.
Fetch product variants for bulk operations, such as updating prices or inventory.
Preload data for product variants, such as inventory items, selected options, or associated products.

The productVariants query supports pagination to handle large product catalogs and saved searches for frequently used product variant queries.

The productVariants query returns product variants with their associated metadata, including:

Basic product variant information (for example, title, SKU, barcode, price, and inventory)
Media attachments (for example, images and videos)
Associated products, selling plans, bundles, and metafields

Learn more about working with Shopify's product model.

ProductVariantConnection arguments

•ProductVariantConnection!

after

•String

The elements that come after the specified cursor.

before

•String

The elements that come before the specified cursor.

first

•Int

The first n elements from the paginated list.

last

•Int

The last n elements from the paginated list.

query

•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to default •string: Filter by a case-insensitive search of multiple fields in a document.
Anchor to barcode •string: Filter by the product variant barcode field.
Anchor to collection •string: Filter by the ID of the collection that the product variant belongs to.
Anchor to delivery_profile_id •id: Filter by the product variant delivery profile ID (ProductVariant.deliveryProfile.id).
Anchor to exclude_composite •boolean: Filter by product variants that aren't composites.
Anchor to exclude_variants_with_components •boolean: Filter by whether there are components that are associated with the product variants in a bundle.
Anchor to gift_card •boolean: Filter by the product isGiftCard field.
Anchor to id •id: Filter by id range.
Anchor to inventory_quantity •integer: Filter by an aggregate of inventory across all locations where the product variant is stocked.
Anchor to location_id •id: Filter by the location ID for the product variant.
Anchor to managed •boolean: Filter by whether there is fulfillment service tracking associated with the product variants.
Anchor to managed_by •string: Filter by the fulfillment service that tracks the number of items in stock for the product variant.
Anchor to option1 •string: Filter by a custom property that a shop owner uses to define product variants.
Anchor to option2 •string: Filter by a custom property that a shop owner uses to define product variants.
Anchor to option3 •string: Filter by a custom property that a shop owner uses to define product variants.
Anchor to product_id •id: Filter by the product id field.
Anchor to product_ids •string: Filter by a comma-separated list of product IDs.
Anchor to product_publication_status •string: Filter by the publication status of the resource on a channel, such as the online store. The value is a composite of the channel app ID (Channel.app.id) and one of the valid values.
Anchor to product_status •string: Filter by a comma-separated list of product statuses.
Anchor to product_type •string: Filter by the product type that's associated with the product variants.
Anchor to publishable_status •string: Filter by the publishable status of the resource on a channel, such as the online store. The value is a composite of either the channel app ID (Channel.app.id) or channel name and one of the valid values.
Anchor to published_status •string: Filter by the published status of the resource on a channel, such as the online store.
Anchor to requires_components •boolean: Filter by whether the product variant can only be purchased with components. Learn more.
Anchor to sku •string: Filter by the product variant sku field. Learn more about SKUs.
Anchor to tag •string: Filter objects by the tag field.
Anchor to tag_not •string: Filter by objects that don’t have the specified tag.
Anchor to taxable •boolean: Filter by the product variant taxable field.
Anchor to title •string: Filter by the product variant title field.
Anchor to updated_at •time: Filter by date and time when the product variant was updated.
Anchor to vendor •string: Filter by the origin or source of the product variant. Learn more about vendors and managing vendor information.

reverse

•Boolean

Default:false

Reverse the order of the underlying list.

savedSearchId

•ID

The ID of a saved search. The search’s query string is used as the query argument.

sortKey

•ProductVariantSortKeys

Default:ID

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to edgesedges •[ProductVariantEdge!]! non-null: The connection between the node and its parent. Each edge contains a minimum of the edge's cursor and the node.
Anchor to nodesnodes •[ProductVariant!]! non-null: A list of nodes that are contained in ProductVariantEdge. You can fetch data about an individual node, or you can follow the edges to fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.
Anchor to pageInfopageInfo •PageInfo! non-null: An object that’s used to retrieve cursor information about the current page.

Was this section helpful?

Retrieve a list of product variants for a product
Retrieve product variants by SKU pattern
Retrieve product variants by available quantity at a location
Retrieve product variants by product IDs
Retrieve product variants by publication statuses
Retrieve the IDs of the first 10 product variants
Retrieve the first three product variants updated after a specified date

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query ProductVariantsList {

productVariants(first: 10, query: "product_id:20995642") {

nodes {

title

}

pageInfo {

startCursor

endCursor

}

}`,

);

const data = await response.json();

query ProductVariantsList {
  productVariants(first: 10, query: "product_id:20995642") {
    nodes {
      id
      title
    }
    pageInfo {
      startCursor
      endCursor
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query ProductVariantsList { productVariants(first: 10, query: \"product_id:20995642\") { nodes { id title } pageInfo { startCursor endCursor } } }"
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  query ProductVariantsList {
    productVariants(first: 10, query: "product_id:20995642") {
      nodes {
        id
        title
      }
      pageInfo {
        startCursor
        endCursor
      }
    }
  }`,
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query ProductVariantsList {
    productVariants(first: 10, query: "product_id:20995642") {
      nodes {
        id
        title
      }
      pageInfo {
        startCursor
        endCursor
      }
    }
  }`,
});

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query ProductVariantsList {
    productVariants(first: 10, query: "product_id:20995642") {
      nodes {
        id
        title
      }
      pageInfo {
        startCursor
        endCursor
      }
    }
  }
QUERY

response = client.query(query: query)

Response

JSON

{

"productVariants": {

"nodes": [

{

"id": "gid://shopify/ProductVariant/30322695",

"title": "151cm"

{

"id": "gid://shopify/ProductVariant/113711323",

"title": "155cm"

{

"id": "gid://shopify/ProductVariant/236948360",

"title": "158cm"

}

"pageInfo": {

"startCursor": "eyJsYXN0X2lkIjozMDMyMjY5NSwibGFzdF92YWx1ZSI6IjMwMzIyNjk1In0=",

"endCursor": "eyJsYXN0X2lkIjoyMzY5NDgzNjAsImxhc3RfdmFsdWUiOiIyMzY5NDgzNjAifQ=="

}