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
Field | Type | Nullable | Description | Related Type(s) |
---|---|---|---|---|
measureUnit | String | Yes | Returns the measure unit name. | |
weightUnit | String | Yes | Returns the weight unit name. | |
unit | String | Yes | Returns the product quantity unit. | |
selected | Boolean | Yes | Returns true if this variant is selected in the product page. | |
image | Image | Yes | Returns the image of the product variant. Alias for featuredImage . | Image |
featuredImage | Image | Yes | Returns the featured image of the product variant. | Image |
previousPrices | PreviousPriceConnection | Yes | Returns information about the previous prices in GraphQL format. | PreviousPriceConnection |
previousLowerPrice | PreviousPrice | Yes | Returns information about the previous lower price in GraphQL format. | PreviousPrice |
isNew | Boolean | Yes | Returns true if products are considered new. | |
option1 | ProductOption | Yes | Returns the first option. | ProductOption |
option2 | ProductOption | Yes | Returns the second option. | ProductOption |
option3 | ProductOption | Yes | Returns the third option. | ProductOption |
options | [ProductOption] | Yes | Returns all options. | [ProductOption] |
url | String | Yes | Returns the URL. | |
id | String | Yes | Returns the ID. | |
title | String | Yes | Returns the title. | |
hasCustomizationsWithPrice | Boolean | Yes | Returns true if some of the customizations increase product price. | |
customizations | [CustomizationGroup] | Yes | The product customization groups for this variant. | [CustomizationGroup] |
inPreview | Boolean | Yes | Returns true if product is in preview. | |
isAvailable | Boolean | Yes | Returns true if product is available for purchase. | |
isDirectlyBuyable | Boolean | Yes | Returns true if product can be bought without selecting any attributes. | |
gtin | String | Yes | Returns the GTIN number. | |
modelNumber | String | Yes | Returns the product model number. | |
rate | Float | Yes | Returns the tax rate. This is the same as the product tax rate. | |
bundleContents | [ProductBundleContent] | Yes | Returns the bundle contents. | [ProductBundleContent] |
discountInformation | ProductDiscount | Yes | Returns the discount if any. | ProductDiscount |
promotion | ProductPromotion | Yes | Returns the promotion if any. | ProductPromotion |
bulkRates | [ProductBulkRate] | Yes | Returns the bulk rates if any. | [ProductBulkRate] |
originalNetPrice | Float | Yes | Returns the original net price without any discounts. | |
originalPrice | Float | Yes | Returns the original price without any discounts. | |
netPrice | Float | Yes | Returns the net price. | |
price | Float | Yes | Returns the price. | |
tax | Float | Yes | Returns the tax amount. | |
isOutOfStock | Boolean | Yes | Returns true if product is out of stock. | |
stockAlarm | Boolean | Yes | Returns true if product is low on stock. | |
discontinuedProduct | Boolean | Yes | Returns true if product won’t be restocked when it runs out of stock. | |
inventoryManagement | String | Yes | Returns the inventory management. | |
notificationsSupported | Boolean | Yes | Returns true if product supports availability notifications. | |
inventoryPolicy | String | Yes | Returns the inventory policy, either “continue” or “deny”. | |
attributeBasedInventory | Boolean | Yes | Returns true if inventory is based on attributes rather than on product itself. | |
stock | Int | Yes | Returns the stock quantity. | |
stockInOtherInventories | Boolean | Yes | Returns true if product has stock set in other inventories. | |
quantitiesInOtherInventories | [InventoryQuantity] | Yes | Returns the stock quantity in other inventories in GraphQL format. | [InventoryQuantity] |
sku | String | Yes | Returns the SKU. | |
deliveryTime | DeliveryTime | Yes | Returns the delivery time in GraphQL format. | DeliveryTime |
weight | Float | Yes | Returns the weight. | |
length | Float | Yes | Returns the length. | |
height | Float | Yes | Returns the height. | |
width | Float | Yes | Returns the width. | |
inCustomersWishlist | Boolean | Yes | Returns true if product is in customer’s wishlist. | |
customerHasPurchased | Boolean | Yes | Returns true if customer has purchased the product. | |
additionalBuyButtons | Boolean | Yes | Returns true if there are additional buy buttons. | |
contentForAdditionalBuyButtons | String | Yes | Returns the content for the additional buy buttons. | |
financingOffers | Boolean | Yes | Returns the financing offers. | |
contentForFinancingOffers | String | Yes | Returns the content for the financing offers. | |
createdAt | String | Yes | Returns the creation date. | |
updatedAt | String | Yes | Returns the last updated date. | |
requiresShipping | Boolean | Yes | Returns 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
andPreviousPrice
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
andProductPromotion
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 viaPreviousPriceConnection
.quantitiesInOtherInventories
provides a list of inventory quantities across different inventories.
Related Types
- 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
andisOutOfStock
to manage product availability UI states. - Leverage
customizations
to present customizable options to customers. - Use
price
,netPrice
, andoriginalPrice
fields to display pricing with or without discounts. - For inventory management, check
stock
,stockInOtherInventories
, andquantitiesInOtherInventories
. - Use filtering and sorting on
isAvailable
andprice
to optimize product listings. - When handling promotions or discounts, utilize
discountInformation
andpromotion
fields. - Consider
requiresShipping
to adjust checkout flows accordingly. - Cache results where possible, especially for static fields like
createdAt
andupdatedAt
, 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
orcustomizations
to avoid performance issues. - The
rate
field reflects the tax rate applicable to the variant and should be used for tax calculations. additionalBuyButtons
andfinancingOffers
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