Paddock — merchant setup guide
This guide shows how to set up your store so that vehicle search, the garage and the fitment badges work. Setup takes about 20 minutes. After that, you only need to add fitment data to your products.
In short: one metaobject definition (section 1), one product metafield (section 2) and, recommended, one filter in Search & Discovery (section 4). Everything else is optional.
1. Create the "Vehicle" metaobject definition
Each vehicle is one metaobject entry: a make, a model, a range of years and, optionally, an engine.
- Shopify admin → Settings → Custom data → Metaobjects → Add definition.
- Name:
Vehicle. Make sure the type is exactlyvehicle, because the theme readsshop.metaobjects.vehicle. - Add these fields with these exact keys:
| Field name | Key | Type | Required | Example |
|---|---|---|---|---|
| Make | make |
Single line text | Yes | Audi |
| Model | model |
Single line text | Yes | R8 |
| Year from | year_from |
Integer | Yes | 2016 |
| Year to | year_to |
Integer | No (empty = still in production) | 2023 |
| Engine | engine |
Single line text | No (empty = all engines) | 5.2 V10 |
- Under Access, turn on Storefronts (read access on the storefront). Without it, the garage stays empty.
- Save. Then create your vehicles in Content → Metaobjects → Vehicle, and make sure each entry's status is Active.
Tips
- Create one entry per consistent range of years, for example "Audi R8 2016–2023 5.2 V10", rather than one entry per year.
- Always spell makes and models the same way ("Volkswagen" everywhere, never "VW" in some entries and "Volkswagen" in others). The theme compares them exactly.
- Universal parts (floor mats, oil, tools…): create one entry with the make Universal (any model and year). Add it to the Fitment field of your universal parts. They get the "Universal fit" badge and stay visible whatever vehicle the shopper has selected.
- No limit on the number of vehicles. The first time a shopper opens the garage, it loads the list in batches of 250. The browser then keeps the list for 6 hours, or until you add or delete a vehicle. Several thousand vehicles work without issue. For tens of thousands (a full ACES-style catalog), a dedicated fitment app is a better fit.
2. Create the product metafields
Shopify admin → Settings → Custom data → Products → Add definition. Use the namespace custom and the exact keys below.
| Name | Namespace and key | Type | What the theme does with it |
|---|---|---|---|
| Fitment | custom.fitment |
Metaobject reference → Vehicle, list of entries | The vehicles the part fits. Drives the badges, the "Fits your…" panel, the fitment table and the "Only show parts that fit" toggle |
| Install difficulty | custom.install_difficulty |
Integer, from 1 to 5 | Install difficulty meter (1 = easy, 5 = professional) |
| Install time | custom.install_time |
Single line text | Install time, shown as written, for example "45 min" |
Turn on Storefronts access for each one.
Then, on each product page of the admin (Metafields section at the bottom), select the vehicles the part fits, or the "Universal" entry.
Shopify allows at most 128 vehicles per product. Use ranges of years ("Audi R8 2016–2023") rather than one entry per year: a part that fits 30 years of models then needs only a few entries.
Bulk import: already have your fitment data (spreadsheet, TecDoc, ACES)? Don't type it in: fill in one fitment sheet and let the offline converter make the import files. See fitment-import/README.md.
3. Theme settings (Customize → Theme settings)
| Group | Setting | Good to know |
|---|---|---|
| Vehicle fitment | Enable garage and fitment | Turn it off for a store that doesn't sell by vehicle (tools, for example): everything related to fitment disappears |
| Show fitment badges on product cards | Shows or hides the badges on product cards. The "Only show parts that fit" toggle still works when they are hidden | |
| Add the vehicle to cart lines | Adds "Vehicle: 2019 Audi R8" to each order line, so you know which vehicle the part was bought for | |
| Shipping | Same-day shipping countdown | Only turn this on if it is true. Set the cutoff hour, the time zone of your warehouse (for example America/New_York) and whether you ship on weekends |
| Free shipping threshold | Amount in your store currency. Leave it empty to hide the progress bar. The bar is hidden for shoppers who pay in another currency | |
| Cart | Cart type | Drawer (recommended) or cart page |
4. Features that rely on Shopify
| Feature | What to do |
|---|---|
| Pay in installments | Turn on Shop Pay Installments (Settings → Payments). The "Pay in installments" block then shows on its own |
| "Complete the job" | In the free Search & Discovery app → Recommendations → Complementary products, choose the related parts for each part (brake pads → rotors, brake fluid…). Without this, the section stays empty |
| Collection filters | In Search & Discovery → Filters, add brand, price, availability, product type and any useful metafields |
| "Only show parts that fit" across the whole collection (recommended) | Search & Discovery → Filters → Add filter → product metafield Fitment. That's all. The theme hides this filter from the filter sidebar and drives it with the toggle. Shopify then filters the whole collection, with correct result counts and pages. Without this filter, the toggle only sorts the page being shown, and a note in the theme editor reminds you |
| Volume pricing (trade customers) | Shopify B2B catalogs (Shopify Plus): the "Volume pricing" table shows automatically |
| Local pickup | Settings → Shipping and delivery → Local pickup |
| Installation request | Uses the Shopify contact form. Requests arrive at your store email with the product, the vehicle and the ZIP code. There is no appointment booking (Shopify Theme Store rules don't allow it) |
5. Check that everything works
- Open your store, click My garage and add a vehicle. The Year → Make → Model → Engine lists should fill in.
- On a part that fits: green "Fits your…" panel, and the vehicle's row highlighted in the fitment table.
- On a collection: "Shopping for…" bar and the "Only show parts that fit" toggle. With the Fitment filter, the counter reads "N parts fit your vehicle"; without it, "X of Y parts on this page fit".
- Add a part to the cart: the drawer opens, and the line shows "Vehicle: …" and the fitment badge.
If the garage is empty: the definition type is not vehicle, Storefronts access is off, or no entry is active.
If every badge says "Check fitment": the metafield is not custom.fitment, or it is not a list of references to Vehicle.
If the toggle only sorts the current page: the Fitment filter is missing in Search & Discovery, or no product in the collection has fitment data.
Known limits
- Without the Search & Discovery Fitment filter, "Only show parts that fit" only applies to the page being shown.
- At most 128 vehicles per product (Shopify limit): use ranges of years.
- The garage is saved in the shopper's browser, not in their customer account.
Cinematic tour
The section shows one photo; while visitors scroll, a camera moves through your blocks, in order.
- Scene: shows the whole photo. Use one to open the tour, one "Parts map" (a bubble for every part) and one to close with a button. Nothing to position.
- Part: one point of the photo (the wheels, a mirror…). The camera zooms on it while visitors scroll, and a bubble with its name appears on the parts map.
- Blurred area: hides a licence plate, a logo or a face.
To position a part, select it: the preview shows the whole photo with a target. Move the "Horizontal position" and "Vertical position" sliders until the target is on the part. The dashed frame shows what the zoom will show.
When you change the photo, set its focal point on the car (scenes are framed on it), then select each part to check its target.
Animations
Theme settings → Animations → "Text reveals and image parallax" (on by default): headings rise word by word, blocks fade in while scrolling, large images drift slower than the page and the hero figures count up. Turn it off for a static store. Visitors whose device asks for reduced motion never see these effects.
Colors and accessibility (WCAG 2.1 AA)
The four styles (Grand Tourer, Service Bay, Superbike, Overland) meet WCAG 2.1 AA contrast. If you change colors, the theme keeps text readable on its own: text in the accent color is darkened or lightened when it would fall below 4.5:1, form field borders and button edges stay at 3:1 or more, and fitment status colors adapt to light and dark backgrounds. Two checks remain yours: the button text color (Colors → Accent text) must contrast with the accent color, and text placed over your own photos needs a dark enough overlay.