Docs/Compatibility metafields

Compatibility metafields

The theme shows part numbers and "Fits your vehicle" badges by reading three product metafields. Here's how they map, how to define them, and how the theme behaves when they're empty.

The Spark Automotive Theme keeps fitment data in Shopify metafields rather than baking it into product descriptions. That means the same data can drive product cards, product pages, quick order, and the Spark Fitment lookup — and stay accurate as your catalog changes.

The three metafields the theme reads

These are the defaults. Every namespace and key below is configurable in theme settings, so you can point the theme at metafields your store already uses.

Purpose Namespace & key Type Example
Compatibility
Drives the "Fits your vehicle" badge		 spark.compatibility List / JSON of fitments [{"make":"Ford","model":"F-150","years":"2015-2020"}]
Part number
Shown on cards & product pages, used by quick order		 spark.part_number Single line text BRK-4471-FR
Fitment summary
Human-readable fit line		 spark.fitment_summary Multi-line text Fits: 2015–2020 Ford F-150 (2.7L, 3.5L, 5.0L)

Already using different metafields? Open Online Store › Themes › Customize › Theme settings › Fitment & compatibility and change the namespace and key for any of the three. The theme will read from wherever you point it.

Create the metafield definitions in Shopify

Defining metafields once gives you a consistent editor field on every product and lets the theme reference them reliably.

  1. Open custom data settings

    In the Shopify admin, go to Settings › Custom data › Products, then click Add definition.

  2. Set the namespace and key exactly

    Under the definition's advanced options, set the namespace and key to match the theme — for example namespace spark and key part_number. These must match character for character, or the theme won't find the value.

  3. Choose the matching type

    Use Single line text for the part number, Multi-line text for the fitment summary, and a list or JSON type for compatibility, depending on how your data is structured.

  4. Save, then add values to products

    After saving, each product's edit page shows a Metafields section where you (or an app) can fill in the values. Repeat for all three definitions.

Tip: The part number metafield does double duty — it powers the on-page part number and improves quick order matching. If you only set up one metafield first, start with spark.part_number.

Let Spark Shipping populate them automatically

Filling metafields by hand across thousands of SKUs isn't realistic. Spark Shipping can map supplier fitment data directly into these metafields as it syncs your catalog, so compatibility badges and part numbers appear without manual entry and stay current as suppliers update their data.

See the Spark Shipping integration guide for how feeds map to spark.compatibility, spark.part_number, and spark.fitment_summary.

What happens when a metafield is empty

Missing metafields hide automatically. If a product has no compatibility data, the "Fits your vehicle" badge simply doesn't render. If there's no fitment summary, that line is skipped. If there's no part number, the part-number label is omitted. You never get empty placeholders, dangling labels, or broken layout — the theme only shows what exists.

This means you can roll fitment data out gradually. Products with data get badges today; products without stay clean until the data arrives — including automatically, once Spark Shipping is filling them.

How this connects to the rest of the theme

  • Quick order — matches shoppers' part numbers against spark.part_number (plus titles, SKUs, and variants).
  • Spark Fitment — the free year/make/model lookup app uses compatibility data to filter products to a shopper's chosen vehicle.
  • Product cards & pages — display the badge, part number, and fitment summary wherever the data is present.

Next: Spark Shipping integration →