🧾 `GetProductOptions` Type

The getProduct() method accepts a single argument of type GetProductOptions. This type controls:

How the product is fetched (by handle or ID)
Which metafields to retrieve and how to parse them
How the final data is transformed and structured

🧠 Interface

export interface GetProductOptions {
  id?: string;
  handle?: string;
  customMetafields?: CustomMetafieldDefinition[];
  variantMetafields?: CustomMetafieldDefinition[];
  options: {
    locale?: string;
    resolveFiles?: boolean;
    renderRichTextAsHtml?: boolean;
    camelizeKeys?: boolean;
    transformMetafields?: (
      raw: Record<string, Record<string, string>>,
      casted: Record<string, any>,
      definitions: ResolvedMetafieldInfo[]
    ) => Record<string, any>;
    transformVariantMetafields?: (
      raw: Record<string, Record<string, string>>,
      casted: Record<string, any>,
      definitions: ResolvedMetafieldInfo[]
    ) => Record<string, any>;
  };
}

🔑 `id` or `handle`

id?: string
handle?: string

You must provide either a Shopify product handle or a gid:// formatted product ID. If neither is defined, the function will return an error.

Using handle is preferred for most storefront implementations.

🧩 `customMetafields`

customMetafields?: CustomMetafieldDefinition[]

An array of typed metafields you want to fetch at the product level.

Each metafield must be defined as:

{ field: "custom.warranty", type: "single_line_text" }

➡️ See full list of supported types in Custom Metafields →

🔀 `variantMetafields`

variantMetafields?: CustomMetafieldDefinition[]

Same format as customMetafields, but applies to each variant within the product.

Useful for variant-level sizing, color, bundle logic, or pricing details.

⚙️ `options`

The nested options object lets you customize how your metafields and data are processed:

`locale?: string`

Specify the locale (e.g., "en", "fr") to get localized product content from Shopify, if available.

`resolveFiles?: boolean`

When true, file metafields (e.g., PDFs, certificates) are resolved into structured objects. Otherwise, a raw GID string is returned.

`renderRichTextAsHtml?: boolean`

If true, rich_text fields will be parsed and returned as HTML strings. This is useful for rendering HTML in your frontend.

`camelizeKeys?: boolean`

When enabled (default), all metafield keys will be camelCased — for example, custom.warranty_period becomes custom.warrantyPeriod.

`transformMetafields`

transformMetafields?: (
  raw, casted, definitions
) => Record<string, any>

Lets you transform product-level metafields after casting — e.g., add summaries, flags, or flatten nested structures.

`transformVariantMetafields`

transformVariantMetafields?: (
  raw, casted, definitions
) => Record<string, any>

Same as above, but applied per variant metafield block.

Useful for:

Bundled product enrichment
Conditional pricing tags
Tagging swatches or options

✅ Example Use

const product = await getProduct({
  handle: "solar-kit-6kw",
  customMetafields: [
    { field: "custom.brand", type: "single_line_text" },
    { field: "custom.weight", type: "decimal" },
  ],
  options: {
    camelizeKeys: true,
    resolveFiles: true,
    transformMetafields: (raw, casted) => ({
      ...casted,
      isHeavy: casted["custom.weight"] > 30,
    }),
  },
});