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

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.

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 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.