ProductVariant Object

Represents a version of a product such as different size or color.

type ProductVariant implements Node & ObjectWithMetadata & ObjectWithAttributes {
  id: ID!
  privateMetadata: [MetadataItem!]!
  privateMetafield(key: String!): String
  privateMetafields(keys: [String!]): Metadata
  metadata: [MetadataItem!]!
  metafield(key: String!): String
  metafields(keys: [String!]): Metadata
  assignedAttribute(slug: String!): AssignedAttribute
  assignedAttributes(limit: PositiveInt = 100): [AssignedAttribute!]!
  name: String!
  sku: String
  product: Product!
  trackInventory: Boolean!
  quantityLimitPerCustomer: Int
  weight: Weight
  channel: String
  channelListings: [ProductVariantChannelListing!]
  pricing(address: AddressInput): VariantPricingInfo
  attributes(variantSelection: VariantAttributeScope): [SelectedAttribute!]! @deprecated(reason: "Use the `assignedAttributes` field instead.")
  margin: Int
  quantityOrdered: Int
  revenue(period: ReportingPeriod): TaxedMoney
  images: [ProductImage!] @deprecated(reason: "Use the `media` field instead.")
  media: [ProductMedia!]
  translation(languageCode: LanguageCodeEnum!): ProductVariantTranslation
  stocks(address: AddressInput @deprecated, countryCode: CountryCode @deprecated(reason: "Use `address` argument instead.")): [Stock!]
  quantityAvailable(address: AddressInput @deprecated, countryCode: CountryCode @deprecated(reason: "Use `address` argument instead.")): Int
  preorder: PreorderData @deprecated(reason: "Preorder is deprecated and will be removed. Model pre-sales with regular stock instead: create the planned quantity in a warehouse, or set `trackInventory` to false to sell without a stock limit.")
  created: DateTime!
  updatedAt: DateTime!
  externalReference: String
}

Interfaces

Node, ObjectWithMetadata, ObjectWithAttributes

Fields

id

id · ID!

The ID of the product variant.

privateMetadata

privateMetadata · [MetadataItem!]!

List of private metadata items. Requires staff permissions to access.

privateMetafield

privateMetafield · String

A single key from private metadata. Requires staff permissions to access.

Tip: Use GraphQL aliases to fetch multiple keys.

privateMetafields

privateMetafields · Metadata

Private metadata. Requires staff permissions to access. Use keys to control which fields you want to include. The default is to include everything.

metadata

metadata · [MetadataItem!]!

List of public metadata items. Can be accessed without permissions.

metafield

metafield · String

A single key from public metadata.

Tip: Use GraphQL aliases to fetch multiple keys.

metafields

metafields · Metadata

Public metadata. Use keys to control which fields you want to include. The default is to include everything.

assignedAttribute

assignedAttribute · AssignedAttribute

Get a single attribute attached to product by attribute slug.

slug

slug · String!

Slug of the attribute

assignedAttributes

assignedAttributes · [AssignedAttribute!]!

List of attributes assigned to this variant.

limit

limit · PositiveInt

Maximum number of attributes to return. Default is 100.

Default: 100.

name

name · String!

The name of the product variant.

sku

sku · String

The SKU (stock keeping unit) of the product variant.

product

product · Product!

The product to which the variant belongs.

Determines if the inventory of this variant should be tracked. If false, the quantity won’t change when customers buy this item. If the field is not provided, Shop.trackInventoryByDefault will be used.

quantityLimitPerCustomer

quantityLimitPerCustomer · Int

The maximum quantity of this variant that a customer can purchase.

weight

weight · Weight

The weight of the product variant.

channel

channel · String

Channel given to retrieve this product variant. Also used by federation gateway to resolve this object in a federated query.

channelListings

channelListings · [ProductVariantChannelListing!]

List of price information in channels for the product.

Requires one of the following permissions:AUTHENTICATED_APPAUTHENTICATED_STAFF_USER

pricing

pricing · VariantPricingInfo

Lists the storefront variant’s pricing, the current price and discounts, only meant for displaying.

address

address · AddressInput

attributes

attributes · [SelectedAttribute!]!

List of attributes assigned to this variant.

variantSelection

variantSelection · VariantAttributeScope

Define scope of returned attributes.

margin

margin · Int

Gross margin percentage value.

quantityOrdered

quantityOrdered · Int

Total quantity ordered.

Requires one of the following permissions:MANAGE_PRODUCTS

revenue

revenue · TaxedMoney

Total revenue generated by a variant in given period of time. Note: this field should be queried using reportProductSales query as it uses optimizations suitable for such calculations.

Requires one of the following permissions:MANAGE_PRODUCTS

period

period · ReportingPeriod

images

images · [ProductImage!]

List of images for the product variant.

media

media · [ProductMedia!]

List of media for the product variant.

translation

translation · ProductVariantTranslation

Returns translated product variant fields for the given language code.

languageCode

languageCode · LanguageCodeEnum!

A language code to return the translation for product variant.

stocks

stocks · [Stock!]

Stocks for the product variant.

Requires one of the following permissions:MANAGE_PRODUCTSMANAGE_ORDERS

address

address · AddressInput

Destination address used to find warehouses where stock availability for this product is checked. If address is empty, uses Shop.companyAddress or fallbacks to server’s settings.DEFAULT_COUNTRY configuration. When Shop.useLegacyShippingZoneStockAvailability is disabled, this argument is ignored — stock availability is determined by the direct warehouse-channel link instead of shipping zones.