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 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
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 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•[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
Adds multiple selling plan groups to a product variant.
- •ID!required
The ID of the product variant.
- Anchor to sellingPlanGroupIdsselling•[ID!]!
Plan Group Ids required The IDs of the selling plan groups to add.
Arguments
- Anchor to productVariantproduct•Product
Variant Variant The product variant object.
- Anchor to userErrorsuser•[Selling
Errors Plan Group User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •ID!
- •mutation
Remove multiple groups from a product variant.
- •ID!required
The ID of the product variant.
- Anchor to sellingPlanGroupIdsselling•[ID!]!
Plan Group Ids required The IDs of the selling plan groups to leave.
Arguments
- Anchor to productVariantproduct•Product
Variant Variant The product variant object.
- Anchor to userErrorsuser•[Selling
Errors Plan Group User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •ID!
- •mutation
Creates new bundles, updates existing bundles, and removes bundle components for one or multiple bundles.
- Anchor to inputinput•[Product
Variant Relationship Update Input!]! required The input options for the product variant being updated.
Arguments
- Anchor to parentProductVariantsparent•[Product
Product Variants Variant!] The product variants with successfully updated product variant relationships.
- Anchor to userErrorsuser•[Product
Errors Variant Relationship Bulk Update User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •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.
- Anchor to mediamedia•[Create
Media Input!] List of new media to be added to the product.
- Anchor to productIdproduct•ID!
Id required The ID of the product on which to create the variants.
- Anchor to strategystrategy•Product
Variants Bulk Create Strategy Default:DEFAULT The strategy defines which behavior the mutation should observe, such as whether to keep or delete the standalone variant (when product has only a single or default variant) when creating new variants in bulk.
- Anchor to variantsvariants•[Product
Variants Bulk Input!]! required An array of product variants to be created.
Arguments
- Anchor to productproduct•Product
The updated product object.
- Anchor to productVariantsproduct•[Product
Variants Variant!] The newly created variants.
- Anchor to userErrorsuser•[Product
Errors Variants Bulk Create User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •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.
- Anchor to allowPartialUpdatesallow•Boolean
Partial Updates Default:false When partial updates are allowed, valid variant changes may be persisted even if some of the variants updated have invalid data and cannot be persisted. When partial updates are not allowed, any error will prevent all variants from updating.
- Anchor to mediamedia•[Create
Media Input!] List of new media to be added to the product.
- Anchor to productIdproduct•ID!
Id required The ID of the product associated with the variants to update.
- Anchor to variantsvariants•[Product
Variants Bulk Input!]! required An array of product variants to update.
Arguments
- Anchor to productproduct•Product
The updated product object.
- Anchor to productVariantsproduct•[Product
Variants Variant!] The updated variants.
- Anchor to userErrorsuser•[Product
Errors Variants Bulk Update User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •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 inputinput•Quantity
Pricing By Variant Update Input! required The input data used to update the quantity pricing in the price list.
- Anchor to priceListIdprice•ID!
List Id required The ID of the price list for which quantity pricing will be updated.
Arguments
- Anchor to productVariantsproduct•[Product
Variants Variant!] The variants for which quantity pricing was created successfully in the price list.
- Anchor to userErrorsuser•[Quantity
Errors Pricing By Variant User Error!]! non-null The list of errors that occurred from executing the mutation.
Fields