Skip to main content

⚙️ getProductVariants() Options

Complete reference for all available options when using getProductVariants().

🔍 Required Options​

variantIds (required)​

  • Type: string[]
  • Description: Array of Shopify variant IDs to fetch
  • Format: ["gid://shopify/ProductVariant/123456789", "gid://shopify/ProductVariant/987654321"]
await getProductVariants({
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
    "gid://shopify/ProductVariant/456789123",
  ],
});

📊 Field Selection​

productFields​

  • Type: string[]
  • Default: ["id", "title", "handle"]
  • Description: Additional product fields to include beyond defaults

Available Fields:

  • "vendor" - Product vendor/brand
  • "productType" - Product type category
  • "tags" - Product tags array
  • "descriptionHtml" - Product description HTML
  • "description" - Product description plain text
  • "images" - All product images
  • "featuredImage" - Featured product image
  • "variants" - All product variants
  • "seo" - SEO title and description
  • "createdAt" - Creation timestamp
  • "updatedAt" - Last update timestamp
await getProductVariants({
  variantIds: ["gid://shopify/ProductVariant/123456789"],
  productFields: [
    "vendor",
    "productType",
    "tags",
    "descriptionHtml",
    "images",
    "variants",
    "seo",
  ],
});

variantFields​

  • Type: string[]
  • Default: ["id", "title"]
  • Description: Additional variant fields to include beyond defaults

Available Fields:

  • "price" - Variant price
  • "compareAtPrice" - Compare at price
  • "availableForSale" - Availability status
  • "selectedOptions" - Selected option values
  • "image" - Variant-specific image
  • "sku" - SKU identifier
  • "barcode" - Barcode value
  • "weight" - Variant weight
  • "weightUnit" - Weight unit
  • "requiresShipping" - Shipping requirement
  • "taxable" - Tax status
  • "inventoryQuantity" - Inventory count
  • "inventoryPolicy" - Inventory policy
await getProductVariants({
  variantIds: ["gid://shopify/ProductVariant/123456789"],
  variantFields: [
    "price",
    "compareAtPrice",
    "availableForSale",
    "selectedOptions",
    "image",
    "sku",
    "weight",
  ],
});

🏷️ Metafields​

productMetafields​

  • Type: CustomMetafieldDefinition[]
  • Description: Product metafields to include in results

variantMetafields​

  • Type: CustomMetafieldDefinition[]
  • Description: Variant metafields to include in results
await getProductVariants({
  variantIds: ["gid://shopify/ProductVariant/123456789"],
  productMetafields: [
    { field: "custom.brand", type: "single_line_text" },
    { field: "custom.warranty_years", type: "number_integer" },
    { field: "custom.specifications", type: "rich_text" },
  ],
  variantMetafields: [
    { field: "custom.sku", type: "single_line_text" },
    { field: "custom.weight", type: "weight" },
    { field: "custom.dimensions", type: "single_line_text" },
  ],
});

CustomMetafieldDefinition​

interface CustomMetafieldDefinition {
  field: string; // e.g., "custom.brand"
  type: MetafieldType; // e.g., "single_line_text"
}

Supported Metafield Types:

  • "single_line_text"
  • "multi_line_text"
  • "rich_text"
  • "number_integer"
  • "number_decimal"
  • "date"
  • "date_time"
  • "boolean"
  • "url"
  • "json"
  • "color"
  • "weight"
  • "volume"
  • "dimension"
  • "rating"
  • "file_reference"
  • "page_reference"
  • "product_reference"
  • "variant_reference"
  • "collection_reference"

🔧 Processing Options​

options​

  • Type: object
  • Description: Additional processing options
await getProductVariants({
  variantIds: ["gid://shopify/ProductVariant/123456789"],
  options: {
    camelizeKeys: true,
    resolveFiles: true,
    renderRichTextAsHtml: true,
    transformProductMetafields: (raw, casted) => ({
      ...casted,
      summary: `${casted["custom.brand"]} - ${casted["custom.model"]}`,
    }),
    transformVariantMetafields: (raw, casted) => ({
      ...casted,
      displayName: `${casted["custom.sku"]} (${casted["custom.weight"]})`,
    }),
  },
});

Processing Options Details:​

camelizeKeys

  • Type: boolean
  • Default: true
  • Description: Convert metafield keys from custom.field_name to customFieldName

resolveFiles

  • Type: boolean
  • Default: true
  • Description: Automatically resolve file metafields to full URLs

renderRichTextAsHtml

  • Type: boolean
  • Default: false
  • Description: Convert rich text metafields to HTML strings

transformProductMetafields

  • Type: MetafieldTransformFn
  • Description: Custom function to transform product metafields

transformVariantMetafields

  • Type: MetafieldTransformFn
  • Description: Custom function to transform variant metafields

MetafieldTransformFn​

type MetafieldTransformFn = (
  raw: Record<string, any>,
  casted: Record<string, any>
) => Record<string, any>;

🧪 Complete Example​

const result = await getProductVariants({
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
    "gid://shopify/ProductVariant/456789123",
  ],
  productFields: [
    "vendor",
    "productType",
    "tags",
    "descriptionHtml",
    "images",
    "variants",
    "seo",
  ],
  variantFields: [
    "price",
    "compareAtPrice",
    "availableForSale",
    "selectedOptions",
    "image",
    "sku",
    "weight",
  ],
  productMetafields: [
    { field: "custom.brand", type: "single_line_text" },
    { field: "custom.warranty_years", type: "number_integer" },
    { field: "custom.specifications", type: "rich_text" },
  ],
  variantMetafields: [
    { field: "custom.sku", type: "single_line_text" },
    { field: "custom.weight", type: "weight" },
    { field: "custom.color_code", type: "color" },
  ],
  options: {
    camelizeKeys: true,
    resolveFiles: true,
    renderRichTextAsHtml: true,
    transformProductMetafields: (raw, casted) => ({
      ...casted,
      displayBrand: casted.customBrand?.toUpperCase(),
      warrantyText: `${casted.customWarrantyYears} year warranty`,
    }),
    transformVariantMetafields: (raw, casted) => ({
      ...casted,
      displayWeight: `${casted.customWeight?.value} ${casted.customWeight?.unit}`,
    }),
  },
});

🔄 Bulk Operations​

Since getProductVariants() handles multiple variants, consider these performance tips:

Batch Size Recommendations​

// Good: Reasonable batch size
const variantIds = ["variant1", "variant2", "variant3"]; // 3-10 variants

// Avoid: Too many variants in one request
const tooManyVariants = Array.from({ length: 100 }, (_, i) => `variant${i}`);

Efficient Field Selection​

// Only request fields you actually need
await getProductVariants({
  variantIds: cartItemIds,
  variantFields: ["price", "availableForSale"], // Minimal for cart validation
  productFields: ["title"], // Just need product name
});

Error Handling for Bulk Operations​

const result = await getProductVariants({
  variantIds: ["valid_id", "invalid_id", "another_valid_id"],
});

// Some variants might fail while others succeed
result.variants.forEach((item, index) => {
  if (item.variant && item.product) {
    console.log(`Variant ${index}: Success`);
  } else {
    console.log(`Variant ${index}: Failed to fetch`);
  }
});

✅ Back to: Overview →

npm version

npm downloads

GitHub stars

GitHub issues

See FAQs

Description

Complete reference for getProductVariants options including fields, metafields, and processing options.