Documentation Your first records

Your first records

Three ways to get compatibility data into ModelMatch — CSV upload, Shopify import with AI mapping, or manual entry.

There are three paths to get compatibility data into ModelMatch, and the right one for you depends mostly on where your data already lives. CSV upload is the most common starting point — it’s for merchants who already have compatibility data in a spreadsheet, whether that came from a manufacturer, a previous app, or your own work building it by hand. Shopify import with AI mapping is for merchants who don’t have prepared data yet but do have a populated Shopify catalog — ModelMatch reads your products and suggests records for you to review. Manual entry is for one-offs and testing. All three paths produce the same result — compatibility records you can manage from the Records page. You can mix and match approaches over time.

Before you start

A few things should be in place before you import:

  • ModelMatch is installed in your store. If you haven’t installed yet, see Installing ModelMatch.
  • You understand what a compatibility record is. If “record,” “mapped,” and “orphaned” don’t mean anything to you yet, take five minutes with Understanding compatibility records. The rest of this page assumes that vocabulary.
  • For Shopify import: you have at least one product in your store. The AI needs something to read.
  • For CSV upload: you have your data in a spreadsheet. Excel, Google Sheets, or a plain .csv file all work — you’ll export to CSV before uploading.

You don’t need to pick one path and stick with it. Plenty of merchants do their initial bulk load via CSV, then use AI mapping when they expand into new product lines, then drop in manual entries to fix one-off issues.

Path 1: CSV upload

Why most merchants start here

CSV is universal. Every parts merchant has a spreadsheet somewhere — a manufacturer-provided cross-reference, an export from a previous compatibility app, a hand-built list of which filters fit which units. CSV upload is the most direct path: you bring clean data, ModelMatch accepts it. There’s no AI involvement, no guesswork, no “the system thinks this fits.” If your row says the part fits the model, the record is created exactly that way.

Preparing your CSV

A valid CSV needs a few specific columns. Required columns:

  • brand
  • model
  • category
  • partSku (or part_sku — both naming styles are accepted)

Optional but strongly recommended columns:

  • series
  • modelAlias (or model_alias)
  • partName (or part_name)

Optional columns for linking records to Shopify products:

  • productVariantId (or product_variant_id)
  • productHandle (or product_handle)
  • productUrl (or product_url)
  • imageUrl (or image_url)

The most important rule: one row per compatibility relationship. If a single part fits ten Honeywell models, that’s ten rows in your CSV — same SKU, same part name, same brand, ten different model values.

A small example to anchor the shape:

brand,series,model,modelAlias,category,partSku,partName
Honeywell,HCM-300 series,HCM-350,HCM350,Wicking Filter,WF-HCM350-4PK,Wicking Filter 4-Pack
Honeywell,HCM-300 series,HCM-300T,,Wicking Filter,WF-HCM350-4PK,Wicking Filter 4-Pack

Two rows, same product (WF-HCM350-4PK), two different compatible models. The second row leaves modelAlias blank because the HCM-300T doesn’t have a common alternate spelling worth tracking.

If you’d rather start from a template than build the column structure yourself, the Connect Data > CSV Upload page has a “Download sample CSV” link that gives you a properly-formatted template with all column headers and a few example rows. Most merchants find it faster to download that, paste their data into it, and re-export than to build the structure from scratch.

[Screenshot: Sample CSV opened in a spreadsheet showing the column headers and a few rows of compatibility data.]

Choosing an import mode

ModelMatch’s CSV upload offers three import modes. Each one handles existing records differently, so picking the right mode matters — especially when you re-upload.

  • Update existing + add new (default, recommended). Updates records that match existing ones (matched by partSku + brand + model) and adds any rows that don’t exist yet. This is the safest default — you can re-upload the same CSV repeatedly without creating duplicates, and corrections to existing records get picked up automatically. Most merchants never need anything else.
  • Add new records only. Skips any rows that match existing records and only adds genuinely new ones. Useful when you want to extend your data set without touching anything that’s already there — for example, you’ve manually corrected a few records and don’t want a fresh CSV upload to overwrite those corrections.
  • Replace all records. Wipes all existing compatibility records for your shop and replaces them with the rows in your CSV. This is destructive. ModelMatch makes you type “REPLACE” to confirm before it runs. Use this only when you’re truly starting fresh, or when you’re certain your CSV is the new source of truth and the existing records should be discarded.

[Screenshot: The three import mode radio cards on the Connect Data > CSV tab.]

Running the import

Once you have your CSV ready and you’ve picked a mode, the actual import is short:

  1. Go to Connect Data > CSV Upload in the ModelMatch admin.
  2. Choose your import mode. The default is fine for most cases.
  3. Click to select your CSV file or drag and drop it into the upload area.
  4. ModelMatch parses the file and shows a preview — verify the columns mapped correctly and the row count looks right.
  5. Click Continue (or Import).
  6. Wait for the import to complete. ModelMatch handles up to 50,000 rows per import on Growth and 200,000 rows per import on Professional.
  7. You’ll see a success message with the count of records added and updated.

If something is wrong — missing required columns, malformed rows, encoding issues — ModelMatch shows clear error messages naming exactly which column or row is the problem. Fix it in your spreadsheet, re-export, and re-upload. Failed imports never partially commit; either the whole batch goes through or none of it does.

[Screenshot: The CSV import preview showing parsed rows ready to be imported.]

Path 2: Shopify import with AI mapping

If you don’t have compatibility data prepared, ModelMatch can suggest records based on your existing Shopify product catalog using AI. The AI reads each product’s title, vendor, type, and SKU; researches compatibility on the open web; and proposes records you can review and approve before saving. This is genuinely useful for merchants who are starting from a populated catalog but no compatibility list — the AI can produce a reasonable first draft of compatibility data in minutes that would otherwise take weeks of manual research. AI mapping is available on every plan, with monthly caps that scale with the tier.

How AI mapping works

The flow, end-to-end:

  1. You select products from your Shopify catalog.
  2. ModelMatch sends each product’s title, vendor, type, and SKU to Claude (Anthropic’s AI).
  3. Claude searches the web for compatibility information specific to that product.
  4. For each product, Claude returns a list of suggested compatibility records — brands, models, series, and confidence levels.
  5. You review each suggestion before anything gets saved.
  6. Approved suggestions become real records in your database.

The most important thing to know: nothing is auto-saved. The AI suggests; you decide. Until you click “Save records,” none of the suggestions exist in your data — you can analyze a hundred products, look at the suggestions, and decide to save zero of them.

Confidence levels

Every AI suggestion comes with a confidence label so you can prioritize what to review:

  • Verified — High confidence. The suggestion is sourced from a manufacturer’s official listing, a major retailer listing, or a published compatibility chart.
  • Likely — Medium confidence. The suggestion was extracted from the product title or pattern-matched from the product’s attributes (for example, a size-based filter compatibility match).
  • Unverified — Low confidence. The AI couldn’t validate the suggestion against a source it considers authoritative.

Each suggestion is also tagged with its source — labels like “Manufacturer official listing,” “Retailer listing,” “Compatibility chart,” “Product title — size-based match,” or “Product title — extracted.” Read the source tag along with the confidence level; both together give you a much better signal than either alone.

⚠️ AI suggestions can contain errors. Even Verified suggestions should be reviewed before saving. The AI does its best to find accurate compatibility data, but you are responsible for the records that end up in your store. Treat AI mapping as a starting point that saves time, not as a final answer.

Running an AI import

The flow in the admin:

  1. Go to Connect Data > Import from Shopify.
  2. Browse or search for products in your Shopify catalog.
  3. Select products you want to analyze. You can select multiple at once — selecting a category or a vendor and analyzing the whole batch is common.
  4. Click Analyze and import.
  5. ModelMatch sends each product to the AI in batches and shows a progress indicator.
  6. When analysis completes, you land on the Review screen with all suggestions grouped per product.
  7. Review each product’s suggestions. You can remove individual suggestions, edit them, or accept them as-is. Removing a suggestion before save means it never becomes a record.
  8. Click Save records to commit the approved suggestions to your database.

If you stop midway and come back later, ModelMatch keeps your in-progress review around — you don’t have to re-analyze the products to pick up where you left off.

Monthly limits

AI mapping has monthly usage caps that vary by plan and reset on the first of each calendar month:

  • Starter: 100 AI mappings per month
  • Growth: 500 AI mappings per month
  • Professional: 2000 AI mappings per month

The Connect Data page shows your current usage so you can see how much of your monthly allowance is left. A “mapping” counts each accepted suggestion, not each product analyzed. If you analyze 100 products and accept five suggestions per product on average, that’s 500 mappings used — your full Growth allotment for the month.

Practical implication: if you have a large catalog and want to map all of it, plan to spread the work across multiple months, or upgrade to Professional for the higher cap. The good news is that once a product has compatibility records, you don’t need to re-analyze it — incremental updates are usually small.

[Screenshot: The AI Review screen showing several products with their suggested compatibility records, confidence badges visible.]

Path 3: Manual entry

For one-off additions, testing, or fixing specific records, manual entry is the fastest path. You add a single record at a time through a simple form. It’s the right tool when you don’t need bulk and don’t want to bother with a CSV. Common uses:

  • Adding records for products that just launched and haven’t made it into your spreadsheet yet
  • Filling gaps after a CSV import (you noticed one model is missing)
  • Testing how the storefront handles a specific compatibility scenario before committing to bulk data
  • Fixing a typo in a single record

Adding a record manually

The flow is short:

  1. Go to Connect Data > Manual Entry.
  2. Fill in the required fields: Brand, Model, Category, Part SKU.
  3. Optionally fill Series, Alias, Part Name, and the product mapping fields if you want to link this record to a specific Shopify product.
  4. Click Save.
  5. The record appears immediately on the Records page.

Validation happens before save. ModelMatch will tell you if a required field is missing or if the data has an obvious problem — for example, a duplicate brand + model + partSku combination that would step on an existing record.

[Screenshot: The manual entry form with all fields visible.]

Mixing approaches

You don’t have to commit to one path forever — and most merchants don’t. A typical pattern looks like this:

  • CSV carries the bulk of the data, both for the initial load and for ongoing periodic updates from a manufacturer cross-reference.
  • Manual entry handles quick fixes, one-offs, and the records that come up between scheduled CSV refreshes.
  • AI mapping comes in when you add a new product line or expand into a new brand you don’t have data for yet.

You can also use CSV import in “Add new records only” mode to layer fresh CSV data on top of records you’ve already created via AI mapping or manual entry, without touching what’s already there. Records from different paths are stored identically — once they’re in your database, ModelMatch doesn’t distinguish CSV records from AI records from manually-entered records. They all show up the same way on the Records page, in the storefront blocks, and in the analytics.

After your first import

Once an import succeeds, a few things are worth doing right away:

  • Visit the Records page and skim your new data. Sort by brand, by model, by status — make sure things look the way you expected.
  • Review the status column. Mapped records are linked to live Shopify products. Unmapped records exist in ModelMatch but have no product link (still useful for compatibility lookups; just no inline add-to-cart). Orphaned records were linked to a Shopify product that’s since been deleted — see Data management for cleanup.
  • Test the shopper experience. Open Test Search in the admin, enter a real brand and model from your data, and confirm you get the expected matches. Test Search runs the same lookup logic the storefront uses, so what you see here is what your shoppers will see.
  • Add the storefront blocks to your theme. A populated database is invisible to shoppers until you actually surface it on your storefront. See Storefront blocks for how to wire up the fit check widget, the standalone finder, and the catalog fit check.
  • If you imported from Shopify, consider enabling auto-sync. Under Connect Data > Settings, you can turn on automatic record creation for new products you add later — the AI runs on each new product as you create it, so your compatibility data stays in step with your catalog.

Once your data is in, the next thing to learn is how it shows up to shoppers. See Storefront blocks for how to add ModelMatch to your theme.