'%20clip-path='url(%23canvas-clip)'/%3e%3cg%20clip-path='url(%23canvas-clip)'%3e%3cg%20transform='rotate(0,%20256,%20256)'%3e%3cg%20transform='translate(87%2087)%20scale(14.083333333333334%2014.083333333333334)%20translate(0%200)'%3e%3cpath%20fill='none'%20stroke='%23FFFFFF'%20stroke-linecap='round'%20stroke-linejoin='round'%20stroke-width='2'%20d='m18.064%2010.877l-4.89-7.26c-.42-.625-1.287-.803-1.936-.397a1.4%201.4%200%200%200-.41.397l-4.893%207.26C4.24%2013.715%204.9%2017.318%207.502%2019.423a7.13%207.13%200%200%200%204.168%201.572M15%2018a3%203%200%201%200%206%200a3%203%200%201%200-6%200m5.2%202.2L22%2022'/%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/svg%3e)
B2B Parts and Compatibility Search on Shopify: Fitment, Exact Identity, and Safe Handoff
A good parts search does not ask whether a result contains the words in the request. It asks whether one exact item satisfies every hard constraint, and it can show the evidence for that answer. Fitment is an intersection, not a similarity score: identity, compatibility, buyer eligibility, availability, and variant handoff must all survive the journey.
This guide shows how to model that intersection for a Shopify B2B catalogue, how to reject plausible but unsafe matches, and how to test the result through the product and cart handoff. It complements the B2B identifier lookup guide, which covers SKU, barcode, and manufacturer-number retrieval. This article owns the harder question: does the item fit?
Decision rule: if a hard compatibility constraint is contradicted, return no match. If it is missing, return partial and name the missing dimension. A plausible family match is not permission to substitute.
Chapter 1 · The boundary
Compatibility is a constraint problem, not a product-title problem
A query such as “cabin air filter for 2019 Civic” contains a product job and a fitment claim. A title can match the product job while saying nothing reliable about the claim. The year may appear in a description, the engine may be absent, and a shared part family may have different mounting or revision requirements. Search can retrieve candidates; only governed fitment data can prove compatibility.
Shopify B2B catalogues solve a different problem. Shopify documents them as controls for the products and pricing assigned to a company or company location. A catalogue can tell you that a buyer may access a product and at what commercial terms. It does not, by itself, prove that the part fits a machine. Keep eligibility and fitment as separate checks, then combine them at the decision boundary.
Retrieval asks
Which records could satisfy the words and structured constraints in this request?
Compatibility asks
Which one has evidence that it works with every required make, model, revision, and use case?
Bridge · From boundary to method
Before building the ledger, watch a plausible answer fail
Suppose the catalogue contains two cabin filters for the same 2019 Civic family. One fits the 2.0L engine and one fits the 1.5L turbo. A search that sees “Civic” can retrieve both, and a ranking model can put one first. Neither step tells the buyer whether the selected part fits the engine they named.
That is the practical problem the next chapter solves. We need a way to keep identity, fitment, eligibility, availability, and handoff visible as separate decisions, so one strong text match cannot hide one failed hard constraint. The constraint ledger is that working method: it turns a natural-language request into values that can be confirmed, left unknown, or contradicted.
Chapter 2 · The constraint ledger
Keep five decisions distinct before you rank anything
Write the request as a ledger of constraints. Each row needs a value, a source, a freshness owner, and a state such as confirmed, unknown, or contradicted. Do not collapse all of it into one relevance score. A result can be highly relevant to the product job and still fail a hard fitment or eligibility constraint.
| Decision | Typed fields | Question | Unsafe failure |
|---|---|---|---|
| Exact identity | sku, mpn, barcode, part_number | Which physical or sellable item is being requested? | A family or near-match is returned without proving the requested identifier. |
| Fitment | make, model, year, engine, revision | Does this part work with the named machine, assembly, or specification? | A shared product word is treated as compatibility evidence. |
| Commercial eligibility | market, company_location, catalogue, customer | May this buyer see and buy this item in this context? | A product that exists in the source catalogue is presented to an ineligible buyer. |
| Availability | inventory, sellability, publication | Can the buyer act on this result now? | A visible result is described as available without checking the active state. |
| Handoff identity | product_id, variant_id, options | Does the next page or cart preserve the exact result? | The product family survives the click but the selected variant does not. |
The Agent-Readable Catalogue guide explains why identity, attribute type, granularity, and freshness need ownership rather than being left as prose in a description.
Chapter 3 · Worked example
A family match is not a fitment match
Use this as an illustrative fixture, not as a claim about a real vehicle catalogue: “cabin air filter, 2019 Honda Civic, 2.0L, carbon, pack of 2.” The part family, vehicle, engine, material, and quantity are separate constraints. A system that returns a filter because its title contains “Civic” has answered only the easiest part of the request.
| Request | Evidence state | State | Safe action |
|---|---|---|---|
| 2019 Honda Civic, 2.0L, cabin filter, carbon, pack of 2 | Exact fitment evidence for 2019 Civic and 2.0L; carbon and pack of 2 match. | exact | Show the matched variant and continue to the eligibility check. |
| 2019 Honda Civic, 1.5L turbo, cabin filter | The product family matches, but the indexed fitment covers only 2.0L. | no_match | Stop or ask for a different part. Do not return the 2.0L part as compatible. |
| 2019 Honda Civic, engine not supplied, cabin filter | Year and model match; engine is required to prove fitment. | partial | Ask for the missing engine dimension and retain the original constraints. |
| 2019 Honda Civic, 2.0L, carbon filter | Two variants match because pack quantity is not specified. | partial | Present the quantity choice. Never select pack of 1 or 2 silently. |
Negative cases are first-class fixtures. If a 1.5L request sees a 2.0L part, that result is not “nearly right”. It is evidence that the search must stop, ask, or route to a verified alternative. Ranking cannot repair missing compatibility truth.
Chapter 4 · Model the evidence
Put fitment at the same granularity as the item it describes
The smallest useful fitment record is the unit a buyer can safely select. If fitment differs by variant, store it at variant level. If it differs by product family, product level may be enough. Do not attach a family-wide “fits Civic” label to every variant when engine, connector, size, or revision changes the result.
Prefer typed, normalised values such as year: 2019, engine: 2.0L,
and pack_quantity: 2 over prose-only claims. Preserve the source and confidence
state beside the value. Unknown is different from not applicable, and both are different
from contradicted. The Agent Search Contract guide shows how to expose that distinction as explicit match state and evidence.
Shopify's variant model gives you a precise sellable grain: each combination of option values is a variant, and inventory is managed per variant. It does not supply the compatibility relationship in this guide. Keep fitment as a separate, merchant-owned source or relationship attached to the product or variant it describes. A search system can retrieve that evidence when it is indexed; it cannot prove fitment or infer a missing engine, connector, or revision from a product title.
Confirmed
A governed source says the value applies to this exact item and revision.
Unknown
The value is required but absent or stale. Ask or stop rather than filling a default.
Contradicted
The source rules out the request. Return no match even if other words look strong.
Chapter 5 · Preserve the result
Fitment proof is incomplete until the exact variant survives the handoff
A search response can prove the right product and still hand off the wrong variant. Return the product identity, the selected variant identity, option values, the fitment evidence, and the active price and availability context together. Then open the product page or cart and verify that the same variant remains selected.
This is where identifier lookup and compatibility meet. The identifier is not merely a token that found a family; it is part of the evidence trail to one sellable unit. A product URL that drops the variant, or a cart action that falls back to the default option, is a failed answer even if the first results page looked perfect.
On a narrow screen, keep the fitment evidence and the selected option visible before the buyer commits. A result that is technically correct but hides the engine, revision, pack quantity, or variant selector behind an unusable horizontal layout is not a safe handoff. Test keyboard focus, touch selection, back navigation, and cart identity on the device classes your buyers actually use.
| Evidence to carry | Check at handoff | If it fails |
|---|---|---|
product_id and variant_id | The destination opens the same item and selected variant. | Stop the action and repair the handoff. Never rely on the default variant. |
| Matched options | Colour, size, connector, pack, or revision still display the requested values. | Ask the buyer to reselect only if the system can preserve and verify the choice. |
| Price and currency | The destination uses the active buyer and market context. | Revalidate and ask for confirmation. Do not describe an old price as current. |
| Availability and eligibility | The buyer can still act on the same item in the same context. | Return a bounded recovery such as unavailable, ineligible, or requires account context. |
The Shopify B2B Search Eligibility guide covers the market, catalogue, customer, pricing, and availability checks that belong beside fitment rather than inside it.
Chapter 6 · Reader-run acceptance test
Prove the positive case, the negative case, and the missing case
Do not approve compatibility search because one familiar query returns a plausible product. The acceptance set must make the system demonstrate that it can match, reject, and ask. Run it with real catalogue records and the buyer contexts your store actually supports.
Create one positive fixture where every hard fitment constraint is present and expected to match one variant.
Create one negative fixture that shares the product family but fails one hard constraint, such as engine or revision.
Create one incomplete fixture where a required constraint is missing. Expect partial, a named missing dimension, and no silent default.
Inspect the result for product identity, variant identity, matched options, evidence, price, availability, and the active market or buyer context.
Open the product handoff and verify that the selected variant remains selected. Add to cart only after the same identity survives the handoff.
Record the query, expected state, actual state, source evidence, and review date. Re-run after catalogue or search changes.
Pass condition: the search never upgrades unknown or contradicted fitment into a confident match, and the exact variant and context remain intact through the handoff.
Research basis
A compatibility framework with explicit boundaries
This is a framework and test plan, not an official Shopify compatibility engine. Shopify's documentation defines product, variant, catalogue, customer, and market concepts. Your fitment truth still needs a governed source, an owner, a normalisation rule, and a review date. Do not publish a compatibility claim merely because search produced a close textual result.
Sources checked August 19, 2026
- B2B Shopify Search guide: The identifier lookup and variant-resolution boundary that this compatibility guide extends.
- Agent-Readable Catalogue guide: The data model for identity, classification, attributes, granularity, and operational freshness.
- Agent Search Contract guide: The match states, variant identity, evidence, and continuation fields a machine-readable answer needs.
- Shopify B2B catalog documentation: Shopify documents catalogues as the mechanism that controls the products and pricing a B2B buyer can access. That is eligibility context, not fitment proof.
- Shopify product variants documentation: Reference for product and variant structure. Confirm the fields and handoff behaviour in the store being tested.
Final judgement
A compatible result is proved, not implied
For parts and technical B2B catalogues, the best search result is not the most similar record. It is the record that satisfies the request, shows why, respects the buyer's eligibility, and preserves its exact variant to the point where the buyer can act. When evidence is missing, the most useful answer is a precise question or a bounded no-match state.