Vehicle fitment

Vehicle fitment lets a shopper choose their vehicle once and see which parts fit it. Chassis stores one record for each vehicle application, which is one model generation with one engine or trim. It does not store make, model and year as separate filters, so a part that fits a 2015 to 2019 car is never shown for a 2020 car by mistake. This page covers what shoppers see, how to set up your vehicle data, how to load it in bulk, and how to fix common problems.

What shoppers get

• Vehicle selector. A cascade of selects: make, model, year and engine (or trim). The home page includes the selector section. Its layout is Hero, Split or Bar. Set the order and the number of steps in the theme settings.
• Saved garage. Shoppers can keep several vehicles and switch between them. The garage is kept in the shopper's browser. It opens from the vehicle plate in the header.
• Vehicle plate. The chosen vehicle is shown as a plate in the header and the footer, in the scope bar on collection and search pages, and in the cart.
• Fit lines. Each product card, product page and cart line shows one of four states:
• Fits: the part fits the chosen vehicle. The line reads "Fits your" and the vehicle name.
• Check: the part fits, but a note applies. Read the note before you buy.
• Does not fit: the part is not listed for the chosen vehicle. The line reads "Does not fit your" and the vehicle name.
• Universal: the part fits every vehicle. The line reads "Fits all vehicles".

No fit line is shown when no vehicle is chosen, or when the product has no fitment data. The theme does not guess. - Vehicle on the order. The chosen vehicle is saved on the cart as two cart attributes, Vehicle and Vehicle ref. The Vehicle attribute is the label the shopper sees, for example "Halden Carvo 2015-2019 2.0 D 150 hp". It appears with the order, so you can check the vehicle before you ship. - Vehicle pages. Each Vehicle entry can have its own page, with its plate, image and links to the categories for that vehicle. - Vehicle directory. A page or section that lists makes and vehicles, so a shopper can pick a vehicle without the selector. The Shop by make page setting (Trade tools) picks the page that lists the makes.

Step 1: Create the Vehicle metaobject definition

A metaobject definition is the template for one kind of record. Create one definition named "Vehicle" with the type vehicle.

1. In the Shopify admin, go to Settings > Metafields and metaobjects > Metaobjects, then click Add definition.
2. Set Name to Vehicle and Type to vehicle.
3. Add the fields in the table below. Use the exact field keys. The theme reads them by key. Add the name field first. The entry's display name and handle are made from it.
4. Keep Storefronts API access turned on. It is on by default. The theme cannot show the vehicles without it.
5. Optional: turn on Publish entries as web pages to create a landing page for each vehicle. The theme uses the vehicle template for these pages.
6. Save the definition.

Step 2: Add Vehicle entries

Add one entry for each model generation and engine, not one for each year. A model that was made from 2015 to 2019 with one engine is one entry with year_from 2015 and year_to 2019. The same model with a second engine is a second entry.

Example entries. All makes and models here are invented for this guide.

1. Go to Content > Metaobjects > Vehicle, then click Add entry.
2. Fill in the fields. The entry's Handle is created from the name field. Note the handle for each entry you will use in fitment notes.
3. Save. Repeat for each generation and engine.

The handle is the key for the fitment notes in Step 5. Keep handles stable. A changed handle breaks the notes that use it.

Step 3: Create the product metafields

Create these product metafield definitions once. They are the data the theme reads for each product.

1. Go to Settings > Metafields and metaobjects > Products, then click Add definition for each row below.
2. Enter the Namespace and key exactly as shown, and choose the Type.

The brand part number is the variant SKU, and the EAN or UPC is the variant barcode. You do not need a metafield for either one.

Step 4: Assign vehicles to a product

1. Open the product in the admin, then scroll to Metafields.
2. In fitment.vehicles, tick each Vehicle entry the product fits. Each entry shows its make, with the handle underneath.
3. Save the product.
4. Check the product page: choose a vehicle that fits, and the fit line should show Fits.

If a product fits every vehicle, turn on fitment.universal and leave the vehicle list empty.

Step 5: Write fitment notes

Use fitment.notes for conditions that apply to some or all of the vehicles. Write one note per line, in one of these two forms:

• handle | note applies the note to one vehicle. The handle is the handle of a Vehicle entry from Step 2.
• A line with no | is a general note. It applies to every vehicle that fits the product.

Example:

halden-carvo-2015-2019-2-0-d-150-hp | Fits the 2015 bracket only.
halden-carvo-2020-2-0-d-150-hp | !Needs the 2020 bracket kit (sold separately).
Fits left and right sides. Sold in pairs.

A note line that starts with ! is a must-read condition. The theme shows the fit line as Check and shows the note, so the shopper sees it before they buy. A note without ! is shown next to Fits as information.

Rules:

• Keep one note per line. Do not break a note across lines.
• Write the note as a short sentence the shopper can act on.
• Use the Vehicle entry handle exactly. A wrong handle is ignored, and the note does not show.
• A ! works in both places: after the | on a vehicle line, and at the start of a general line. The theme removes the ! and shows the note as a must-read condition.
• If a vehicle line matches the shopper's vehicle, the theme shows that note. Otherwise it shows the first general line only.
• A | inside a note is shown as /.
• Notes show only when the product fits the chosen vehicle.

Step 6: Mark universal parts

For a part that fits every vehicle, such as a bulb kit that is sold for all engines, turn on fitment.universal and leave fitment.vehicles empty. Every vehicle then shows Fits all vehicles. Use this only when you are sure. A wrong universal flag sends shoppers the wrong part.

Step 7: Filtered collections (optional)

The theme always marks parts on cards as fits or does not fit. A filtered list, where "Fits my vehicle" shows only the matching parts with correct counts and pages, needs one more step. It uses Shopify's free Search & Discovery app.

1. Install Search & Discovery from the Shopify App Store, or open it if it is already installed. It is Shopify's own app.
2. Open Search & Discovery > Filters, then add a filter on the product metafield fitment.vehicles.
3. Save. The theme adds the switch "Fits my vehicle" to collection pages once a vehicle is chosen.

What the filtered list holds:

• "Fits my vehicle" shows the products that list the chosen vehicle in fitment.vehicles.
• Parts marked fitment.universal list no vehicles, so they are not in the filtered list. A line under the list says so and links to all parts, where these parts show Fits all vehicles.
• A collection in which no product lists vehicles, such as fluids, shows no switch. Its cards are marked as usual.

Without this filter:

• Cards are still marked and sorted by fit.
• The switch "Fits my vehicle" is hidden.
• The collection shows all parts. The page does not hide parts that do not fit.

Step 8: Load the data in bulk

Choose the route that fits your store size. The theme does not care how the data arrived.

Route 1: by hand (up to about 200 vehicles). Create each Vehicle entry in Content > Metaobjects, then assign vehicles to each product in the admin, as in Step 4.

Route 2: product CSV with metafield columns. Export your products with Products > Export, add columns for the product metafields, and import the file with Products > Import.

• Variant metafields are not supported in product CSV import. The fitment and parts fields in this guide are product metafields, so this does not affect them.

Route 3: Vehicle entries in bulk with Shopify CLI. Shopify's free Shopify CLI can run a GraphQL file against your store. A GraphQL file can create many Vehicle entries in one run, using the field keys from Step 1. No app is needed.

• Start with five entries, check them in the admin, then run the full list.

Route 4: an import app. If you already use a data import app for your catalog, the theme reads its output the same way. Check what the app writes to each field key in Step 1.

The Vehicle entries list in the admin has no import or export button. Create the entries by hand (Route 1), with the Shopify CLI (Route 3), or with an import app (Route 4).

Theme settings for fitment

Open Theme settings > Vehicle fitment.

The Shop by make page setting is in the Trade tools settings. It picks the page that lists the makes.

The vehicle selector section has its own settings: "Layout" ("Hero", "Split" or "Bar"), "Heading", "Image", "Image overhang", "Link label", "Link" and "Button label". Set them on the section in the theme editor.

Limits

• The selector loads its data in pages of 250 entries and keeps a copy in the shopper's browser. A change to the entries appears after the shopper reloads the page.

Troubleshooting

The selector is empty. 1. Check that at least one Vehicle entry exists in Content > Metaobjects > Vehicle. 2. Check that the definition has Storefronts API access turned on. 3. Check that Show vehicle fitment is on. 4. Reload the page. A browser that loaded the list before the first entries were added keeps the old copy until it reloads.

A product shows no fit line. 1. The line is hidden when no vehicle is chosen. Choose a vehicle first. 2. The product has no data. Check that fitment.vehicles lists the vehicle, or that fitment.universal is on. 3. The chosen vehicle is not in the product's list. This shows "Does not fit", not a blank line. 4. Check that Show fit on product cards is on for cards, or that the product page includes the Fitment verdict block.

The switch "Fits my vehicle" is missing. 1. This is expected until the Search & Discovery filter on fitment.vehicles is added. See Step 7. 2. The switch also needs a chosen vehicle.

A vehicle note does not show. 1. Check the Vehicle entry handle in the note line. It must match the entry's handle exactly. 2. Check the | separator and that the note is on its own line. 3. Check that the product fits the chosen vehicle. Notes show only with a Fits line.

The vehicle is not on the cart. 1. Check that Show fit in cart is on for the fit line. The Vehicle attribute is saved with the cart whenever a vehicle is chosen.

Open live tests

These points are not yet confirmed on a live store. Check each one on a development store before launch. If one fails, the fallback is noted.

1. The vehicle list is read in pages of 250 inside a section. Fallback: the selector loads the pages again after a change.
2. How a product's vehicle list appears in Liquid. Fallback: the check reads each entry in turn.
3. The filter URL format for a metaobject reference filter. Fallback: no filtered switch; cards are marked only.
4. Cart attributes appear on the next page view. Fallback: the page reloads after a vehicle is chosen.
5. The product CSV header and separator for a list of references (Step 8, route 2).
6. Whether Search & Discovery can search the OEM numbers. Fallback: OEM numbers are also read from product tags with the prefix in OEM tag prefix. See Part numbers and search.
7. The metaobject template and how the theme reads the entry ID in Liquid.