Product Variant
Requires access scope.
The object represents a 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 object to manage the full lifecycle and configuration of a product's variants. Common
use cases for using the
object include:
- Tracking inventory for each variant
- Setting unique prices for each variant
- Assigning barcodes and SKUs to connect variants to fulfillment services
- Attaching variant-specific images and media
- Setting delivery and tax requirements
- Supporting product bundles, subscriptions, and selling plans
A is associated with a parent
Product
object.
serves as the central link between a product's merchandising configuration, inventory,
pricing, fulfillment, and sales channels within the GraphQL Admin API schema. Each variant
can reference other GraphQL types such as:
: Used for inventory tracking
Image
: Used for variant-specific images: Used for subscriptions and selling plans
Learn more about Shopify's product model.
Anchor to Fields and connectionsFields and connections
- Anchor to availableForSaleavailable•Boolean!
For Sale non-null Whether the product variant is available for sale.
- Anchor to barcodebarcode•String
The value of the barcode associated with the product.
- Anchor to compareAtPricecompare•Money
At Price The compare-at price of the variant in the default shop currency.
- Anchor to contextualPricingcontextual•Product
Pricing Variant Contextual Pricing! non-null The pricing that applies for a customer in a given context. As of API version 2025-04, only active markets are considered in the price resolution.
- Anchor to createdAtcreated•Date
At Time! non-null The date and time when the variant was created.
- Anchor to defaultCursordefault•String!
Cursor non-null A default cursor that returns the single next record, sorted ascending by ID.
- Anchor to deliveryProfiledelivery•Delivery
Profile Profile The delivery profile for the variant.
- Anchor to deliveryPromiseParticipantsdelivery•[Delivery
Promise Participants Promise Participant!]! non-null The delivery promise participants for the product variant.
- Anchor to displayNamedisplay•String!
Name non-null Display name of the variant, based on product's title + variant's title.
- •ID!non-null
A globally-unique ID.
- Anchor to imageimage•Image
The featured image for the variant.
- Anchor to inventoryIteminventory•Inventory
Item Item! non-null The inventory item, which is used to query for inventory information.
- Anchor to inventoryPolicyinventory•Product
Policy Variant Inventory Policy! non-null Whether customers are allowed to place an order for the product variant when it's out of stock.
- Anchor to inventoryQuantityinventory•Int
Quantity The total sellable quantity of the variant.
- Anchor to legacyResourceIdlegacy•Unsigned
Resource Id Int64! non-null The ID of the corresponding resource in the REST Admin API.
- Anchor to metafieldmetafield•Metafield
A custom field, including its
namespace
andkey
, that's associated with a Shopify resource for the purposes of adding and storing additional information.- Anchor to metafieldsmetafields•Metafield
Connection! non-null A list of custom fields that a merchant associates with a Shopify resource.
- Anchor to metafieldsByIdentifiersmetafields•[Metafield]!
By Identifiers non-null The metafields associated with the resource matching the supplied list of namespaces and keys.
- Anchor to positionposition•Int!non-null
The order of the product variant in the list of product variants. The first position in the list is 1.
- Anchor to priceprice•Money!non-null
The price of the product variant in the default shop currency.
- Anchor to productproduct•Product!non-null
The product that this variant belongs to.
- Anchor to productParentsproduct•Product
Parents Connection! non-null A list of products that have product variants that contain this variant as a product component.
- Anchor to productVariantComponentsproduct•Product
Variant Components Variant Component Connection! non-null A list of the product variant components.
- Anchor to requiresComponentsrequires•Boolean!
Components non-null Whether a product variant requires components. The default value is
false
. Iftrue
, then the product variant can only be purchased as a parent bundle with components and it will be omitted from channels that don't support bundles.- Anchor to selectedOptionsselected•[Selected
Options Option!]! non-null List of product options applied to the variant.
- Anchor to sellableOnlineQuantitysellable•Int!
Online Quantity non-null The total sellable quantity of the variant for online channels. This doesn't represent the total available inventory or capture limitations based on customer location.
- Anchor to sellingPlanGroupsselling•Selling
Plan Groups Plan Group Connection! non-null A list of all selling plan groups defined in the current shop associated with the product variant.
- Anchor to sellingPlanGroupsCountselling•Count
Plan Groups Count Count of selling plan groups associated with the product variant.
- Anchor to showUnitPriceshow•Boolean!
Unit Price non-null Whether to show the unit price for this product variant.
- •String
A case-sensitive identifier for the product variant in the shop. Required in order to connect to a fulfillment service.
- Anchor to taxabletaxable•Boolean!non-null
Whether a tax is charged when the product variant is sold.
- Anchor to taxCodetax•String
Code The tax code for the product variant.
- Anchor to titletitle•String!non-null
The title of the product variant.
- Anchor to translationstranslations•[Translation!]!non-null
The published translations associated with the resource.
- Anchor to unitPriceunit•Money
Price V2 The unit price value for the variant based on the variant measurement.
- Anchor to unitPriceMeasurementunit•Unit
Price Measurement Price Measurement The unit price measurement for the variant.
- Anchor to updatedAtupdated•Date
At Time! non-null The date and time (ISO 8601 format) when the product variant was last modified.
Deprecated fields and connections
- Anchor to metafieldDefinitionsmetafield•Metafield
Definitions Definition Connection! non-nullDeprecated - Anchor to presentmentPricespresentment•Product
Prices Variant Price Pair Connection! non-nullDeprecated - Anchor to sellingPlanGroupCountselling•Int!
Plan Group Count non-nullDeprecated - Anchor to storefrontIdstorefront•Storefront
Id ID! non-nullDeprecated
Anchor to QueriesQueries
- •query
Retrieves a product variant by its ID.
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
query when you need to:
- Access essential product variant data (for example, title, price, image, and metafields).
- Build product detail pages and manage inventory.
- Handle international sales with localized pricing and content.
- Manage product variants that are part of a bundle or selling plan.
Learn more about working with Shopify's product model.
- •query
Return a product variant by an identifier.
- •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
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
query supports pagination to handle large product catalogs and saved searches for frequently used product variant queries.
The
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.
Anchor to MutationsMutations
- •mutation
Appends media from a product to variants of the product.
- Anchor to productIdproduct•ID!
Id required Specifies the product associated to the media.
- Anchor to variantMediavariant•[Product
Media Variant Append Media Input!]! required A list of pairs of variants and media to be attached to the variants.
Arguments
- Anchor to productproduct•Product
The product associated with the variants and media.
- Anchor to productVariantsproduct•[Product
Variants Variant!] The product variants that were updated.
- Anchor to userErrorsuser•[Media
Errors User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •mutation
Detaches media from product variants.
- Anchor to productIdproduct•ID!
Id required Specifies the product to which the variants and media are associated.
- Anchor to variantMediavariant•[Product
Media Variant Detach Media Input!]! required A list of pairs of variants and media to be deleted from the variants.
Arguments
- Anchor to productproduct•Product
The product associated with the variants and media.
- Anchor to productVariantsproduct
Variants
Fields