Documentation Mapping records to products

Mapping records to products

How compatibility records connect to your Shopify products, why mapping matters for shoppers, and how to find and fix unmapped records.

A compatibility record is the link between a piece of equipment and a Shopify product. When a shopper enters their model number, ModelMatch checks for matching records and shows them the parts that fit. But the record can only do its job if it’s connected to a real Shopify product in your store. This is called mapping.

What mapping means

Every compatibility record stores two things: information about the equipment it fits (brand, model, optional category) and information about the Shopify product that’s compatible with that equipment. The second part — the product side — is the mapping.

A record is mapped when it has at least one of these:

  • A product handle (the URL slug of a Shopify product, like pecohepa-filter-2-pack)
  • A product variant ID (a specific variant of a Shopify product)

If a record has either of these, ModelMatch can build a working link from the storefront to a real product in your store. The fit check widget can show a “View product” button. The finder can show search results with valid product cards. The shopper can navigate to the product and add it to their cart.

A record is unmapped when it has neither a product handle nor a product variant ID. The record exists in your admin — you can see it on the Records page — but ModelMatch has no real Shopify product to link it to. From the shopper’s perspective, it’s as if the record doesn’t exist.

Why mapping matters

ModelMatch deliberately hides unmapped records from shoppers. Here’s why.

If a shopper enters their model number and ModelMatch finds an unmapped record that matches, there’s no Shopify product to send them to. The result would be a card with a “View” button that goes nowhere — a broken link. That breaks trust at the exact moment the shopper is deciding whether to buy.

To prevent this, unmapped records are filtered out of three places on the storefront:

  • The product-page fit check widget
  • The catalog fit check on collection pages
  • The standalone finder

If a shopper enters a brand and model number that only matches unmapped records, they see “No matching parts found” or “Not confirmed for your model” — not a broken result. The unmapped record stays invisible until you map it.

This means mapping is essential for ModelMatch to actually help shoppers. A record without a mapped product can’t reach them.

How records get mapped

There are four ways records arrive in ModelMatch, and three of them map automatically.

Shopify product import. When you use the Build compatibility data tab to import products from your Shopify catalog, every product comes in pre-mapped. The product handle, variant ID, product URL, and image URL are all populated automatically. This is the most reliable path — every record has a working storefront link from the moment it’s created.

AI mapping. When you ask ModelMatch to generate compatibility data for your products, the AI builds records that are already tied to the products you selected. Each record arrives mapped. You review the suggestions before they’re saved, and you can adjust any that look wrong before approval.

CSV upload with SKU or product handle. When you upload a CSV, ModelMatch tries to auto-map each row to a Shopify product. It looks for an exact SKU match against any variant in your store, or an exact match on the product handle column. When it finds one, the record auto-maps. Rows that don’t match any Shopify product become unmapped records that you can link later.

Manual entry. When you enter records manually, you can paste a product handle or product variant ID directly. Records entered this way are only mapped if you provide those fields explicitly.

In practice, most merchants end up with a mix. Shopify product import and AI mapping produce mapped records by default. CSV upload and manual entry produce mapped records only when the matching information is included.

Finding unmapped records

The Records page has a health strip at the top showing three counts: Mapped, Unmapped, and Orphaned. Mapped records are visible to shoppers. Unmapped records are not. Orphaned records had a valid mapping at some point but the underlying Shopify product was deleted — they need to be remapped or removed.

To see only your unmapped records, use the Mapped status filter on the Records page. Set it to Unmapped and the table will show only records that aren’t reaching shoppers. From here you can:

  • Edit a record manually to add the product handle or variant ID
  • Re-run Shopify product import if you’ve added new products to your store
  • Run AI mapping on the products that should be associated with those records
  • Delete records you no longer need

The goal is to drive the Unmapped count toward zero — or at least to make sure the records that remain unmapped are intentional (records you’re keeping for future products you plan to add).

Edge cases

A record with only a product handle, no variant ID. This is still mapped. The shopper sees a “View product” button that takes them to the product. They won’t see an “Add to cart” button on the result card, but the navigation works. This is a valid state.

A record with only a variant ID, no product handle. This is also mapped. ModelMatch builds the product URL from other fields when needed.

A record with both fields populated. This is fully mapped — the shopper gets both “View product” and “Add to cart” functionality on the result card.

Orphaned records. When you delete a product from your Shopify store, any records linked to that product are flagged as orphaned. Orphaned records are also hidden from shoppers, since clicking the result would lead to a 404. Orphaned records appear in the Unmapped filter on the Records page and in the Orphaned count on the health strip. To resolve, either map them to a different Shopify product or delete them.

A brand and model with mixed mapped and unmapped records. This is the common case. A shopper enters their model, ModelMatch returns only the mapped records, and the unmapped ones stay invisible. The shopper sees a clean result; you keep working on the unmapped ones in admin.

Keeping your data healthy

Mapping isn’t a one-time task — it’s part of how you maintain a healthy compatibility catalog over time. Whenever you add new products to your Shopify store, run Shopify product import or AI mapping to keep records connected. Whenever you delete products, check the Orphaned count and resolve them. Whenever you bulk-import via CSV, check the Mapped status filter to find any rows that didn’t auto-map and link them manually.

The merchants who get the most out of ModelMatch are the ones who treat the Records page as a living workspace. The Mapped status filter exists to make that easy — one click to see exactly what’s missing.