Skip to Content

ProductVariant

Describes a product variant, representing a specific version or configuration of a product. This type provides detailed information about the variant’s attributes, pricing, availability, inventory, images, and related metadata.

Type Definition

type ProductVariant { measureUnit: String weightUnit: String unit: String selected: Boolean image: Image featuredImage: Image previousPrices: PreviousPriceConnection previousLowerPrice: PreviousPrice isNew: Boolean option1: ProductOption option2: ProductOption option3: ProductOption options: [ProductOption] url: String id: String title: String hasCustomizationsWithPrice: Boolean customizations: [CustomizationGroup] inPreview: Boolean isAvailable: Boolean isDirectlyBuyable: Boolean gtin: String modelNumber: String rate: Float bundleContents: [ProductBundleContent] discountInformation: ProductDiscount promotion: ProductPromotion bulkRates: [ProductBulkRate] originalNetPrice: Float originalPrice: Float netPrice: Float price: Float tax: Float isOutOfStock: Boolean stockAlarm: Boolean discontinuedProduct: Boolean inventoryManagement: String notificationsSupported: Boolean inventoryPolicy: String attributeBasedInventory: Boolean stock: Int stockInOtherInventories: Boolean quantitiesInOtherInventories: [InventoryQuantity] sku: String deliveryTime: DeliveryTime weight: Float length: Float height: Float width: Float inCustomersWishlist: Boolean customerHasPurchased: Boolean additionalBuyButtons: Boolean contentForAdditionalBuyButtons: String financingOffers: Boolean contentForFinancingOffers: String createdAt: String updatedAt: String requiresShipping: Boolean }

Fields

FieldTypeNullableDescriptionRelated Type(s)
measureUnitStringYesReturns the measure unit name.
weightUnitStringYesReturns the weight unit name.
unitStringYesReturns the product quantity unit.
selectedBooleanYesReturns true if this variant is selected in the product page.
imageImageYesReturns the image of the product variant. Alias for featuredImage.Image
featuredImageImageYesReturns the featured image of the product variant.Image
previousPricesPreviousPriceConnectionYesReturns information about the previous prices in GraphQL format.PreviousPriceConnection
previousLowerPricePreviousPriceYesReturns information about the previous lower price in GraphQL format.PreviousPrice
isNewBooleanYesReturns true if products are considered new.
option1ProductOptionYesReturns the first option.ProductOption
option2ProductOptionYesReturns the second option.ProductOption
option3ProductOptionYesReturns the third option.ProductOption
options[ProductOption]YesReturns all options.[ProductOption]
urlStringYesReturns the URL.
idStringYesReturns the ID.
titleStringYesReturns the title.
hasCustomizationsWithPriceBooleanYesReturns true if some of the customizations increase product price.
customizations[CustomizationGroup]YesThe product customization groups for this variant.[CustomizationGroup]
inPreviewBooleanYesReturns true if product is in preview.
isAvailableBooleanYesReturns true if product is available for purchase.
isDirectlyBuyableBooleanYesReturns true if product can be bought without selecting any attributes.
gtinStringYesReturns the GTIN number.
modelNumberStringYesReturns the product model number.
rateFloatYesReturns the tax rate. This is the same as the product tax rate.
bundleContents[ProductBundleContent]YesReturns the bundle contents.[ProductBundleContent]
discountInformationProductDiscountYesReturns the discount if any.ProductDiscount
promotionProductPromotionYesReturns the promotion if any.ProductPromotion
bulkRates[ProductBulkRate]YesReturns the bulk rates if any.[ProductBulkRate]
originalNetPriceFloatYesReturns the original net price without any discounts.
originalPriceFloatYesReturns the original price without any discounts.
netPriceFloatYesReturns the net price.
priceFloatYesReturns the price.
taxFloatYesReturns the tax amount.
isOutOfStockBooleanYesReturns true if product is out of stock.
stockAlarmBooleanYesReturns true if product is low on stock.
discontinuedProductBooleanYesReturns true if product won’t be restocked when it runs out of stock.
inventoryManagementStringYesReturns the inventory management.
notificationsSupportedBooleanYesReturns true if product supports availability notifications.
inventoryPolicyStringYesReturns the inventory policy, either “continue” or “deny”.
attributeBasedInventoryBooleanYesReturns true if inventory is based on attributes rather than on product itself.
stockIntYesReturns the stock quantity.
stockInOtherInventoriesBooleanYesReturns true if product has stock set in other inventories.
quantitiesInOtherInventories[InventoryQuantity]YesReturns the stock quantity in other inventories in GraphQL format.[InventoryQuantity]
skuStringYesReturns the SKU.
deliveryTimeDeliveryTimeYesReturns the delivery time in GraphQL format.DeliveryTime
weightFloatYesReturns the weight.
lengthFloatYesReturns the length.
heightFloatYesReturns the height.
widthFloatYesReturns the width.
inCustomersWishlistBooleanYesReturns true if product is in customer’s wishlist.
customerHasPurchasedBooleanYesReturns true if customer has purchased the product.
additionalBuyButtonsBooleanYesReturns true if there are additional buy buttons.
contentForAdditionalBuyButtonsStringYesReturns the content for the additional buy buttons.
financingOffersBooleanYesReturns the financing offers.
contentForFinancingOffersStringYesReturns the content for the financing offers.
createdAtStringYesReturns the creation date.
updatedAtStringYesReturns the last updated date.
requiresShippingBooleanYesReturns true if product requires shipping.

Relationships

  • image and featuredImage fields link to the Image type, providing visual representation of the variant.
  • previousPrices and previousLowerPrice relate to PreviousPriceConnection and PreviousPrice types respectively, offering historical pricing data.
  • option1, option2, option3, and options connect to ProductOption type(s), representing variant options such as size or color.
  • customizations links to an array of CustomizationGroup, describing customizable aspects of the variant.
  • bundleContents relates to [ProductBundleContent], detailing bundled products included with this variant.
  • discountInformation and promotion connect to ProductDiscount and ProductPromotion types, providing promotional details.
  • bulkRates links to [ProductBulkRate], describing pricing for bulk purchases.
  • quantitiesInOtherInventories connects to [InventoryQuantity], showing stock levels across multiple inventories.
  • deliveryTime relates to DeliveryTime, indicating estimated delivery durations.

Usage Examples

Basic Query

{ productVariant(id: "12345") { id title price isAvailable stock sku } }

Field Selection

{ productVariant(id: "12345") { title options { name value } price discountInformation { amount description } isOutOfStock requiresShipping } }

Nested Queries

{ productVariant(id: "12345") { id title featuredImage { url altText } customizations { id name options { id label priceAdjustment } } bundleContents { productId quantity title } } }

Filtering and Sorting

{ productVariants(filter: { isAvailable: true }, sort: { field: "price", direction: ASC }, first: 10) { edges { node { id title price stock } } pageInfo { hasNextPage endCursor } } }

Implements

This type does not explicitly implement any interfaces.

Connections

  • previousPrices provides a connection to previous pricing data via PreviousPriceConnection.
  • quantitiesInOtherInventories provides a list of inventory quantities across different inventories.
  • Image: Represents images associated with the variant.
  • PreviousPriceConnection & PreviousPrice: Provide historical pricing information.
  • ProductOption: Defines options such as size, color, or material.
  • CustomizationGroup: Groups of customizable options for the product variant.
  • ProductBundleContent: Details of bundled products included with the variant.
  • ProductDiscount: Discount information applicable to the variant.
  • ProductPromotion: Promotion details for the variant.
  • ProductBulkRate: Bulk pricing rates.
  • InventoryQuantity: Stock quantities in various inventories.
  • DeliveryTime: Estimated delivery times.

Best Practices

  • Use the id field to uniquely identify variants in queries and mutations.
  • When displaying variant images, prefer featuredImage for consistency.
  • Utilize isAvailable and isOutOfStock to manage product availability UI states.
  • Leverage customizations to present customizable options to customers.
  • Use price, netPrice, and originalPrice fields to display pricing with or without discounts.
  • For inventory management, check stock, stockInOtherInventories, and quantitiesInOtherInventories.
  • Use filtering and sorting on isAvailable and price to optimize product listings.
  • When handling promotions or discounts, utilize discountInformation and promotion fields.
  • Consider requiresShipping to adjust checkout flows accordingly.
  • Cache results where possible, especially for static fields like createdAt and updatedAt, to improve performance.

Notes

  • All fields are optional and may return null if data is unavailable.
  • The API currently requires no authentication but this may change in future versions.
  • Pricing fields (price, netPrice, originalPrice) reflect the current state and may be affected by promotions or customizations.
  • The selected field indicates if the variant is currently selected on the product page, useful for UI state management.
  • Use caution when querying large nested fields like previousPrices or customizations to avoid performance issues.
  • The rate field reflects the tax rate applicable to the variant and should be used for tax calculations.
  • additionalBuyButtons and financingOffers fields provide flags for enhanced purchase options, with corresponding content fields for display.
  • Stock-related fields provide comprehensive inventory status, including attribute-based inventory and stock across multiple locations.
  • Dates (createdAt, updatedAt) are in ISO 8601 string format.
  • Use the url field to link directly to the variant’s product page when available.
Last updated on