Documentation Understanding compatibility records

Understanding compatibility records

What a record is, what each field means, and how records connect your products to the equipment they fit.

Records are the foundation of ModelMatch. Every fit check on a product page, every result in the standalone finder, every compatibility answer a shopper sees — all of it traces back to a record. Before you import a CSV, before you wire up the storefront blocks, before you send your first shopper to a product page, it’s worth a few minutes to understand what a record is and what each field on it is doing. The rest of the product is built on top of this one concept, so the time you spend here pays back fast.

What a record actually is

A record is a single compatibility relationship: this part is compatible with this specific equipment. That’s it.

If you sell a wicking filter that fits the Honeywell HCM-350 humidifier, you’d have a record tying your filter to the HCM-350. If the same filter also fits the HCM-300T, that’s a second record. The HCM-310T? A third. The part is the same; the equipment differs; each combination is its own row in your compatibility data.

This is why one product typically has many records. A single replacement filter might fit ten or twenty Honeywell models — each one needs its own record so a shopper searching for any of those models gets a hit. Multiply that across a catalog of two hundred filter SKUs and you’re already in the tens of thousands of records. Normal merchant catalogs run anywhere from a few thousand records up to two hundred thousand on the largest plan. ModelMatch is built to handle that comfortably.

[Screenshot: Records page showing several records with mixed brands and models, status column visible.]

The fields on a record

Every record has the same set of fields. A few are required; the rest are optional but improve the shopper experience meaningfully when filled in. Walk through them once and you’ll know how to read every record in your catalog.

Brand

Required. The manufacturer of the equipment the part fits. Examples: Honeywell, Dyson, Coway, Levoit, Vicks. This is what shoppers type first when searching, so it has to match how the brand is commonly written. Don’t use abbreviations or alternate spellings unless that’s how the brand actually appears on the equipment itself. “GE” and “General Electric” are not the same string — pick whichever the brand uses on its products and stay consistent across every record.

Series

Optional, recommended where it applies. A grouping label for related models within a brand. The GermGuardian AC4300, AC4825, and AC4850 are all part of the “AC4000 series” — that label, on every record for those models, helps shoppers who know they own “an AC4000-something” but can’t remember the exact suffix. Same idea for “HCM-300 series” covering HCM-300T, HCM-305T, HCM-310T.

Leave Series blank if the brand doesn’t use a meaningful series naming convention. Don’t write the literal word “Series” or “Family” as a placeholder — an empty series is fine, a junk series confuses shopper searches.

Model

Required. The specific model number of the equipment. Examples: “HCM-350”, “AC4825”, “Core 300”, “Air Mini+”. This is the exact identifier the shopper enters during a fit check.

Use the model number as it appears on the equipment, including hyphens, plus signs, and spaces. Don’t normalize “Core 300” to “Core300” or “AP-1512HH” to “AP1512HH”. The shopper is going to copy what’s printed on their equipment label, and small punctuation differences will cause a no-match.

Alias

Optional. An alternate way the same model might be written. If the official model is “HCM-350”, common aliases might be “HCM350” (no hyphen) or “HCM 350” (with a space). Aliases catch shoppers who type the model differently than how it’s officially printed. Use them when you know a single model gets searched in multiple variations — for example, a model that appears one way on the equipment label and another way in the user manual.

You don’t need an alias on every record. Add them where you’ve actually seen variation, or where the official punctuation is unusual enough that shoppers will probably drop it.

Category

Required. The type of part this is — your own naming, kept consistent across records. Examples: “Filter”, “Replacement Filter”, “Wicking Filter”, “Furnace Filter”.

Categories are labels you choose, not predefined options. ModelMatch doesn’t care what your categories are; it just uses them to group records logically and to let shoppers browse by type. The important word here is consistent. If half your filter records are tagged “Filter” and the other half are tagged “Replacement Filter”, you’ve split a single category into two and weakened both.

Part SKU

Optional, recommended. Your internal SKU or part number for the product that fits this compatibility entry. Examples: “WF-HCM350-4PK”, “FILTER-001”. The SKU is what helps you (the merchant) identify which of your products a record represents — especially useful when several different products in your catalog fit the same equipment.

Part name

Optional. A human-readable name for the part. Examples: “Wicking Filter 4-Pack”, “Replacement HEPA Filter”. Part name is what you’ll see in the Records list when you’re scrolling through compatibility entries. SKUs help machines; part names help you.

Linking to a Shopify product

Records can optionally link to a specific Shopify product or variant in your store. When linked, ModelMatch can show shoppers the actual product image, take them to the product page from finder results, and even add to cart directly without leaving the finder. Mapped records are a meaningfully better shopper experience than unmapped ones.

Four optional fields enable this:

  • productVariantId — The Shopify variant ID this record corresponds to. It’s a technical ID that looks like gid://shopify/ProductVariant/12345. This gets auto-populated when you import compatibility data from Shopify or when you use AI-assisted mapping. You can also paste one in manually for advanced cases.
  • productHandle — The Shopify product handle (the part of the URL slug, like wicking-filter-4pack). Lets ModelMatch construct product page URLs without an extra API call.
  • productUrl — The full product page URL. Auto-derived from the handle, but can be customized if you serve product pages on a non-standard URL pattern.
  • imageUrl — The image to show shoppers in finder results. Auto-pulled from the linked Shopify product when one is available.

Records without product mapping still work for compatibility matching — a shopper can still verify “yes, this fits your equipment” — but they won’t see product images and won’t be able to add to cart from inside the finder. They’ll see a confirmation, but they have to go find the product themselves on your storefront.

[Screenshot: A single record opened in edit mode showing all fields, with a Shopify product visibly mapped.]

Status (computed, not user-editable)

Every record has a status that ModelMatch computes automatically based on whether the record is mapped to a real Shopify product. You don’t set this field; it sets itself, and it changes as your Shopify catalog changes.

  • Mapped — The record is linked to a real Shopify product. The productVariantId is set, and that product still exists in your store.
  • Unmapped — The record exists in ModelMatch but isn’t linked to any Shopify product. Compatibility lookups still work, but shoppers won’t be able to go directly to a product from the finder.
  • Orphaned — The record was previously linked to a Shopify product, but that product has since been deleted. The compatibility data is preserved, but the product link is broken.

Status appears as a column in the Records page. Orphaned records get an amber warning treatment so you can spot them at a glance. ModelMatch checks for orphaned records automatically — the cadence depends on your plan — and you can run a manual orphan check anytime from the Records page. Bulk cleanup tools live alongside the check; the full workflow is documented under Data management once that page exists.

How records connect to your storefront

Records are abstract until they reach a shopper. There are three places that happens.

  1. Fit check widget on product pages. When a shopper visits a product page, the fit check widget reads any records linked to that product and lets the shopper enter their equipment to verify a match. The widget auto-hides on products that have no records yet, so partial coverage doesn’t show as a broken UI.
  2. Standalone finder. A dedicated page or section where shoppers enter brand and model and ModelMatch searches all your records for matches. It returns the products that fit (from mapped records) plus any unmapped records — those still show up as “yes, this is compatible,” they just can’t add to cart inline.
  3. Catalog fit check. On collection pages, the block asks shoppers to set their equipment once, then continuously checks every product they browse against your compatibility data. Same record set as the other two surfaces.

All three storefront features draw from the same record pool. Adding a record once makes it available everywhere — there’s no need to re-enter or re-tag data per surface.

How records get into ModelMatch

There are three import paths, and most merchants end up using more than one.

  • CSV upload — Best when you already have compatibility data prepared in a spreadsheet. This is the most common starting point, especially for merchants migrating from another system or working off a manufacturer-provided cross-reference.
  • Shopify import with AI mapping — Best when you don’t have compatibility data yet but you do have a populated Shopify catalog. ModelMatch reads your products and suggests records based on product titles, descriptions, and metafields. Available on every plan, with monthly caps that scale with the tier (Starter 100/month, Growth 500/month, Professional 2000/month).
  • Manual entry — Best for one-off additions, testing how a record behaves on the storefront, or filling gaps after a CSV import.

The full walkthrough for each path lives in Importing your data.

A few practical tips

  • Use consistent brand spelling. “GE” and “General Electric” should pick one and stick with it across every record. Inconsistency splits shopper searches in half and weakens both halves.
  • Add aliases for models that get typed multiple ways. Common patterns: hyphen vs no hyphen (“HCM-350” vs “HCM350”), space vs no space, included vs omitted suffix letters.
  • Keep categories simple and few. Five to ten categories is usually enough. Fifty categories means most are wasted — and that you’ve probably split a few real categories into many smaller ones that each get diluted.
  • Map records to Shopify products whenever possible. A mapped record is a meaningfully better shopper experience. AI mapping makes this practical even for large catalogs.
  • Run a manual orphan check after deleting Shopify products. Records pointing to deleted products go orphan automatically on the next scheduled check, but a manual run confirms the cleanup immediately.
  • Don’t worry about being perfect on day one. Record sets improve over time as you watch what shoppers actually search for and where the no-matches cluster. Insights will tell you where to focus.

Ready to add your first records? See Importing your data for the three ways to get compatibility data into ModelMatch.