Skip to main content

🏷️ GetProductVariantsOptions

TypeScript interface defining all available options for the getProductVariants() function.

📋 Interface Definition​

interface GetProductVariantsOptions {
  variantIds: string[];
  productFields?: string[];
  variantFields?: string[];
  productMetafields?: CustomMetafieldDefinition[];
  variantMetafields?: CustomMetafieldDefinition[];
  options?: {
    camelizeKeys?: boolean;
    resolveFiles?: boolean;
    renderRichTextAsHtml?: boolean;
    transformProductMetafields?: MetafieldTransformFn;
    transformVariantMetafields?: MetafieldTransformFn;
  };
}

🔍 Core Properties​

variantIds (required)​

  • Type: string[]
  • Description: Array of Shopify variant IDs to fetch
  • Format: ["gid://shopify/ProductVariant/123456789", "gid://shopify/ProductVariant/987654321"]
const options: GetProductVariantsOptions = {
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
    "gid://shopify/ProductVariant/456789123",
  ],
};

📊 Field Selection​

productFields​

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

Available Values:

type ProductField =
  | "vendor"
  | "productType"
  | "tags"
  | "descriptionHtml"
  | "description"
  | "images"
  | "featuredImage"
  | "variants"
  | "seo"
  | "createdAt"
  | "updatedAt";

variantFields​

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

Available Values:

type VariantField =
  | "price"
  | "compareAtPrice"
  | "availableForSale"
  | "selectedOptions"
  | "image"
  | "sku"
  | "barcode"
  | "weight"
  | "weightUnit"
  | "requiresShipping"
  | "taxable"
  | "inventoryQuantity"
  | "inventoryPolicy";

🏷️ Metafield Configuration​

productMetafields​

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

variantMetafields​

  • Type: CustomMetafieldDefinition[]
  • Optional: Yes
  • Description: Variant metafields to include in results

CustomMetafieldDefinition​

interface CustomMetafieldDefinition {
  field: string;
  type: MetafieldType;
}

type MetafieldType =
  | "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
  • Optional: Yes
  • Description: Additional processing configuration
interface ProcessingOptions {
  camelizeKeys?: boolean;
  resolveFiles?: boolean;
  renderRichTextAsHtml?: boolean;
  transformProductMetafields?: MetafieldTransformFn;
  transformVariantMetafields?: MetafieldTransformFn;
}

Processing Option Details:​

camelizeKeys

  • Type: boolean
  • Default: true
  • Description: Convert metafield keys to camelCase

resolveFiles

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

renderRichTextAsHtml

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

transformProductMetafields

  • Type: MetafieldTransformFn
  • Description: Custom product metafield transformation

transformVariantMetafields

  • Type: MetafieldTransformFn
  • Description: Custom variant metafield transformation

MetafieldTransformFn​

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

🧪 Usage Examples​

Basic Options​

const basicOptions: GetProductVariantsOptions = {
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
  ],
};

With Additional Fields​

const withFields: GetProductVariantsOptions = {
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
  ],
  productFields: ["vendor", "productType", "images"],
  variantFields: ["price", "availableForSale", "selectedOptions"],
};

With Metafields​

const withMetafields: GetProductVariantsOptions = {
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
  ],
  productMetafields: [
    { field: "custom.brand", type: "single_line_text" },
    { field: "custom.warranty_years", type: "number_integer" },
  ],
  variantMetafields: [
    { field: "custom.sku", type: "single_line_text" },
    { field: "custom.weight", type: "weight" },
  ],
};

Complete Configuration​

const completeOptions: GetProductVariantsOptions = {
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
    "gid://shopify/ProductVariant/456789123",
  ],
  productFields: [
    "vendor",
    "productType",
    "tags",
    "descriptionHtml",
    "images",
    "variants",
  ],
  variantFields: [
    "price",
    "compareAtPrice",
    "availableForSale",
    "selectedOptions",
    "image",
    "sku",
  ],
  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 Operation Considerations​

Batch Size Recommendations​

// Good: Reasonable batch size (3-10 variants)
const reasonableBatch: GetProductVariantsOptions = {
  variantIds: [
    "gid://shopify/ProductVariant/123456789",
    "gid://shopify/ProductVariant/987654321",
    "gid://shopify/ProductVariant/456789123",
  ],
};

// Avoid: Too many variants (performance impact)
const largeBatch = Array.from(
  { length: 50 },
  (_, i) => `gid://shopify/ProductVariant/${i}`
);

Efficient Field Selection​

// Minimal fields for cart validation
const cartValidation: GetProductVariantsOptions = {
  variantIds: cartItemIds,
  variantFields: ["price", "availableForSale"],
  productFields: ["title"], // Just need product name
};

// Rich data for product comparison
const productComparison: GetProductVariantsOptions = {
  variantIds: comparisonIds,
  productFields: ["vendor", "images", "tags"],
  variantFields: ["price", "compareAtPrice", "selectedOptions"],
  productMetafields: [{ field: "custom.brand", type: "single_line_text" }],
};

Dynamic Variant ID Arrays​

// From cart items
const cartItemIds = cartItems.map((item) => item.variantId);

// From wishlist
const wishlistIds = wishlist.map((item) => item.variantId);

// From recently viewed (localStorage)
const recentlyViewedIds = JSON.parse(
  localStorage.getItem("recentlyViewed") || "[]"
);

const options: GetProductVariantsOptions = {
  variantIds: [...cartItemIds, ...wishlistIds, ...recentlyViewedIds],
  variantFields: ["price", "availableForSale"],
  productFields: ["title", "images"],
};

✅ Next: Result Types →

npm version

npm downloads

GitHub stars

GitHub issues

See FAQs

Description

TypeScript interface for getProductVariants options parameter.