Product
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 trackingImage: Used for variant-specific images: Used for subscriptions and selling plans
Learn more about Shopify's product model.
Anchor to FieldsFields
- 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 displayNamedisplay•String!
Name non-null Display name of the variant, based on product's title + variant's title.
- Anchor to eventsevents•Event
Connection! non-null The paginated list of events associated with the host subject.
- •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 mediamedia•Media
Connection! non-null The media associated with the product variant.
- Anchor to metafieldmetafield•Metafield
A custom field, including its
namespaceandkey, 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 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 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
- 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 taxCodetax•String
Code Deprecated
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.
- •mutation
Detaches media from product variants.
- •mutation
Adds multiple selling plan groups to a product variant.
- •mutation
Remove multiple groups from a product variant.
- •mutation
Creates new bundles, updates existing bundles, and removes bundle components for one or multiple bundles.
- •mutation
Creates multiple product variants for a single product in one operation. You can run this mutation directly or as part of a bulk operation for large-scale catalog updates.
Use the
mutation to efficiently add new product variants—such as different sizes, colors, or materials—to an existing product. The mutation is helpful if you need to add product variants in bulk, such as importing from an external system.The mutation supports:
- Creating variants with custom options and values
- Associating media (for example, images, videos, and 3D models) with the product or its variants
- Handling complex product configurations
NoteBy default, stores have a limit of 100 product variants for each product. You can create a development store and enable the Extended Variants developer preview to create a maximum of 2,048 product variants in a single operation.
After creating variants, you can make additional changes using one of the following mutations:
: Updates multiple product variants for a single product in one operation.: Used to perform multiple operations on products, such as creating or modifying product options and variants.
You can also specifically manage product options through related mutations:
Learn more about the product model and adding product data.
- •mutation
Updates multiple product variants for a single product in one operation. You can run this mutation directly or as part of a bulk operation for large-scale catalog updates.
Use the
mutation to efficiently modify product variants—such as different sizes, colors, or materials—associated with an existing product. The mutation is helpful if you need to update a product's variants in bulk, such as importing from an external system.The mutation supports:
- Updating variants with custom options and values
- Associating media (for example, images, videos, and 3D models) with the product or its variants
- Handling complex product configurations
NoteBy default, stores have a limit of 100 product variants for each product. You can create a development store and enable the Extended Variants developer preview to update a maximum of 2,048 product variants in a single operation.
After creating variants, you can make additional changes using the
mutation, which is used to perform multiple operations on products, such as creating or modifying product options and variants.You can also specifically manage product options through related mutations:
Learn more about the product model and adding product data.
- •mutation
Updates quantity pricing on a price list. You can use the
mutation to set fixed prices, quantity rules, and quantity price breaks. This mutation does not allow partial successes. If any of the requested resources fail to update, none of the requested resources will be updated. Delete operations are executed before create operations.
Anchor to InterfacesInterfaces
- •interface
- •interface
- •interface
- •interface