Metafields reference

This is the canonical reference for every product metafield Torquex reads. The theme’s automotive features — the Year/Make/Model fitment selector, the “Fits your vehicle” badge, the technical-specs table, the install-difficulty badge, the compare table, and structured data — are driven entirely by product metafields in the custom namespace. No third-party app is required: these are native Shopify metafields you create once under Settings → Custom data → Products and then fill in per product.

Every metafield is optional. Products without any of these metafields still display and sell normally — the theme simply skips whatever isn’t set. See Products without metafields at the end of this page.

For the merchant-facing walkthrough of these features in the storefront, see Automotive features. For where the data surfaces on the product page, see Product pages.

The metafield contract at a glance

All seven metafields live in the custom namespace — no other namespace appears anywhere in the theme. The Key column below is the full namespace.key you enter as the “Namespace and key” when creating the definition.

Key	Definition type	Value format / example	What it powers	Where it appears
custom.fitment	JSON	Array of vehicle objects, e.g. [{"year":2021,"make":"Toyota","model":"Tacoma","trim":"TRD Pro"}]	Year/Make/Model fitment selector, “Fits your vehicle” badge, fitment tab table	Product page (selector, badge, Fitment tab); product cards in collection & search grids (badge)
custom.install_difficulty	Single line text	Exactly easy, moderate, or professional (lowercase)	Installation-difficulty badge with wrench icon	Product badges, Installation tab, product card, compare table
custom.weight_kg	Decimal	Bare number, no unit, e.g. 12.5 (theme adds ” kg”)	Weight row in spec tables	Specifications tab, compare table
custom.dimensions	Single line text	Free-form with your own units, e.g. 120 x 80 x 30 cm	Dimensions row in spec tables	Specifications tab, compare table
custom.material	Single line text	Free-form, e.g. 6061-T6 Aluminum	Material row in spec tables	Specifications tab, compare table
custom.warranty	Single line text	Free-form, e.g. 2 years or Lifetime	Warranty row in spec tables	Specifications tab, compare table
custom.part_number	Single line text	Free-form SKU/part string, e.g. TQX-1042-BLK	Part number — overrides variant SKU, feeds JSON-LD	SKU block, spec tables, compare table, cart page line, Product structured data

Note

Keys are case-sensitive. Use the exact namespace custom and the exact key shown. A typo (for example custom.Fitment or a different namespace) means the theme reads nothing for that field — it does not throw an error, it just renders nothing.

custom.fitment — the vehicle fitment data

This is the metafield behind every fitment feature. It is a JSON metafield holding an array of objects, one object per supported vehicle.

JSON shape

Each object uses lowercase, case-sensitive keys:

• year — required. A number (cleanest) or a numeric string. The theme parseInts it for sorting and compares it lowercased as a string for matching, so both 2021 and "2021" work.
• make — required. Vehicle make, e.g. Toyota.
• model — required. Vehicle model, e.g. Tacoma.
• trim — optional. Shown only in the Fitment tab’s Trim column. When omitted, that cell falls back to an em dash (—).

The value is an array of objects (not an object of arrays). Order does not matter — the fitment selector sorts years numerically descending and makes/models alphabetically, and de-duplicates automatically, so you can simply list every vehicle row.

Worked multi-vehicle example

[
  { "year": 2021, "make": "Toyota", "model": "Tacoma", "trim": "TRD Pro" },
  { "year": 2021, "make": "Toyota", "model": "Tacoma", "trim": "SR5" },
  { "year": 2020, "make": "Ford",   "model": "F-150" },
  { "year": 2022, "make": "Jeep",   "model": "Wrangler", "trim": "Rubicon" }
]

This product fits four vehicle configurations. Notice:

• Two rows share the same Year/Make/Model (2021 Toyota Tacoma) but different trims — the selector treats them as one Tacoma entry, and the Fitment tab lists both trim rows.
• The Ford F-150 row omits trim entirely — that’s allowed, and its Trim cell shows —.
• year is written as a number throughout, which is the cleanest form.

What it powers

When custom.fitment has a value, the theme renders:

• The cascading Year → Make → Model selector on the product page. Selecting a vehicle saves it to the visitor’s browser and reports an inline fit / no-fit result.
• The “Fits your vehicle” badge, which is hydrated from the visitor’s saved vehicle and shows when their saved vehicle matches any entry. This badge appears on the product page and on every product card — collection grids, search results, and the Featured products section — except the recently-viewed and product-recommendation carousels, where it is suppressed.
• The Fitment tab table, which lists every entry with a Year, Make, Model, and Trim column.

When the metafield is empty or absent, none of these render — the selector, badge, and the fitment tab all guard against a blank value.

Caution

The fit/no-fit matching compares only year, make, and model. trim is informational and is shown in the Fitment tab table; it is not part of the match. If a customer’s saved vehicle’s year/make/model matches any entry, the product is reported as a fit regardless of trim.

custom.install_difficulty — the installation badge

A Single line text metafield whose value must be exactly one of these three lowercase keywords:

Value	Badge label (English)
easy	Easy install
moderate	Moderate install
professional	Pro install

The label text comes from the theme’s locale files, so it translates automatically when you switch the theme language. The badge renders with a wrench icon. Any value other than these three renders no badge at all — there is no fallback, so a misspelling like Easy (capitalized) or pro simply shows nothing.

To prevent typos, set up a Choices (list of values) validation on the definition restricting it to exactly easy, moderate, professional — see the creation steps below.

The install-difficulty badge appears on the product page badges, in the Installation tab, on the product card in collections, and in the compare table.

custom.weight_kg — weight

A Decimal metafield (use Integer instead if your weights are always whole numbers). Store the number only — no unit. The theme appends ” kg” itself.

• Correct: 12.5 → renders as 12.5 kg
• Wrong: 12.5 kg → renders as 12.5 kg kg

It powers the Weight row in the Specifications tab’s tech-specs table and the Weight row of the compare table.

custom.dimensions, custom.material, custom.warranty — free-form spec rows

These three are Single line text metafields printed verbatim — the theme applies no transformation and adds no units, so include any units yourself.

Key	Example value	Powers
custom.dimensions	120 x 80 x 30 cm or 12" x 8" x 3"	Dimensions row in the spec table and compare table
custom.material	6061-T6 Aluminum	Material row in the spec table and compare table
custom.warranty	2 years or Lifetime	Warranty row in the spec table and compare table

In the compare table, any of these (and part_number) that is blank for a product falls back to an em dash (—) so columns stay aligned. In the Specifications tab, blank rows are skipped entirely; if all spec metafields are blank, the tech-specs table is omitted and the tab shows a “No information available for this product.” empty-state message instead (the Specifications tab itself does not disappear).

custom.part_number — the SKU / part number

A Single line text metafield holding a part number or SKU string, printed verbatim (e.g. TQX-1042-BLK). This field does more than display a row:

• It is shown in the Part number row of the spec table and compare table.
• It is used by the SKU block on the product page, where it is preferred over the variant’s Shopify SKU. If custom.part_number is blank, the SKU block falls back to the selected variant’s SKU.
• It overrides the per-variant sku in the variant data JSON that the product media controller reads.
• It is shown as the SKU on each line of the full Cart page. (The cart drawer shows the variant’s native Shopify SKU instead, not this metafield.)
• It populates the sku property in the product’s schema.org Product structured data (JSON-LD), which search engines read.

Because it overrides the variant SKU everywhere it appears, use custom.part_number only when you want one canonical part number for the whole product. If different variants need different SKUs, leave this metafield blank and let Shopify’s native per-variant SKU flow through.

Note

The SKU block is optional and is not in the default product template, so the on-page SKU does not show until you add it. In the theme editor, open the product template, add a SKU block to the product information area, and save. The other places custom.part_number surfaces (spec tables, compare table, Cart page, structured data) work without it.

Create the definitions

Create each definition once for your whole store. In your Shopify admin:

1. 1 Open Custom data
2. 2 Add a definition
3. 3 Set the exact type
4. 4 Save and repeat

1 Open Custom data

Go to Settings → Custom data → Products.

2 Add a definition

Click Add definition and fill it in using the rows below. The Namespace and key field must be custom plus the key shown (for example, enter custom.fitment).

3 Set the exact type

Set the Type exactly as listed — this matters, especially the JSON type for fitment.

4 Save and repeat

Save, then repeat for the next definition until all seven exist.

← Back

Next →

#	Namespace and key	Name (suggested)	Type	Validation
1	custom.fitment	Fitment	JSON	None. One value per product.
2	custom.install_difficulty	Install difficulty	Single line text	Add a Choices / list of values limit with exactly easy, moderate, professional (all lowercase)
3	custom.weight_kg	Weight (kg)	Decimal (or Integer if always whole)	None. Store the number only.
4	custom.dimensions	Dimensions	Single line text	None
5	custom.material	Material	Single line text	None
6	custom.warranty	Warranty	Single line text	None
7	custom.part_number	Part number	Single line text	None

Tip

Adding the Choices validation to custom.install_difficulty is the single most useful safeguard here. With the list set to easy / moderate / professional, editors pick from a dropdown and cannot type an unsupported value that would silently render no badge.

After the definitions exist, populate values on individual products under each product’s Metafields section (scroll to the bottom of the product page in admin, or open the product’s metafields panel). The namespace is custom for every field.

Bulk-populate values (CSV / import)

For large catalogs, set metafield values in bulk instead of one product at a time:

• Shopify CSV import. Once a definition exists under Settings → Custom data → Products, Shopify’s product CSV export includes a column for it, named like Metafield: custom.weight_kg [number_decimal]. Export your products, fill in the metafield columns, and re-import. For custom.fitment, the cell contains the entire JSON array as a single string — paste the full [ ... ] array; mind your spreadsheet’s quote-escaping so the JSON survives the round trip.
• Bulk editor. In admin, select products in your product list and use Bulk edit (or Edit products) to add the metafield columns and type values inline — convenient for the text fields (install_difficulty, dimensions, material, warranty, part_number).
• Validate the JSON before importing fitment. Because custom.fitment is JSON, an invalid array (a stray comma, a missing bracket, smart quotes pasted from a word processor) means the selector and badge read an empty list and render nothing. Run your array through a JSON validator first, and keep the keys lowercase: year, make, model, trim.
• Reuse trims wisely. Listing many {year, make, model} rows is fine — the selector de-duplicates and sorts them. You don’t need to pre-sort or pre-dedupe your data.

Products without metafields still sell

None of these metafields are required. A product with no fitment, no specs, and no install difficulty renders a clean, fully functional product page — gallery, price, variants, and Add to cart all work normally. The theme guards every metafield-driven element on a non-blank value and simply omits anything that isn’t set:

• No custom.fitment → no selector, no vehicle badge, no Fitment tab content.
• No spec metafields → the Specifications tab’s tech-specs table is omitted, and the tab shows a “No information available for this product.” empty-state message (the tab itself stays).
• No custom.install_difficulty → no install badge.
• No custom.part_number → the SKU block falls back to the variant SKU, and JSON-LD simply omits the sku property.

Add metafields where they add value, and leave them blank where they don’t. Nothing breaks either way.

Need help mapping your catalog to these fields? See Automotive features, or reach out via Torquex support — we reply within 12 hours.