How matching works
How FurniOps decides that two sources' records are the same item. Deterministic identifiers first, then a trained probabilistic model with embeddings, then an AI judge that must quote its evidence, and people for everything in doubt.
Two vendors often sell the same item: a maker's feed and a dealer's price list, or two dealers. Matching decides when two sources' variants are one item, so the item gets one master record with an offer from each source. Matching decides variants; their products follow.
It works in layers, from the most certain to the least. Each layer merges only what it is sure of, and passes the rest down. Everything in doubt goes to people.
deterministic a shared GTIN, or brand + part number merged unseen
│
probabilistic a trained model scores every comparison merged unseen above the merge
│ threshold; reviewed in the band below
AI judge picks among candidates, quoting both records merged only when grounded and sure
│
people review queue: merge or dismiss every merge can be undone1. Deterministic
Two variants are one item when they share:
- a GTIN (UPC or EAN) that is unique the world over, or
- a brand and a part number: a SKU or an MPN on either side, since a dealer's "vendor SKU" is the maker's SKU.
GTINs that are not one trade item everywhere (store-internal, regional and coupon ranges) never match. Brands are compared with case, punctuation and company forms ("Inc.", "LLC") set aside.
Contradicting evidence vetoes a merge: one GTIN on two brands, or one part number on two GTINs. And because these merges are the ones nobody reviews, every doubt refuses one: a variant with two possible partners, two products fed by the same source (a source lists an item once, so two of its records that agree are its own duplicates, for a person), and a pair a person already pulled apart.
2. Probabilistic
Variants without a shared identifier are compared field by field and scored by a model trained on your catalogue:
| Comparison | |
|---|---|
name, brand, collection, category | The product's words. |
finish, dimensions, pieces | What tells one item from its neighbours. |
price | Prices in the same range. |
image | The hero pictures. |
embedding | An embedding of the variant's text and hero picture: closeness in meaning, not in spelling. |
Each comparison has an agreement level and a weight in bits, for or against; together they give a match probability. A pair is then:
- merged at or above the merge threshold, when nothing decisive disagrees;
- offered for review in the band below it, or whenever a decisive conflict (another finish, another size) shows, however high the score;
- left alone below the review threshold.
The model and its thresholds are your catalogue's own: trained on its records, then refined by your people's decisions, per category where there are enough. A small catalogue gets a starter model that only offers pairs for review, never merges. A catalogue too small for either is not scored yet.
3. The AI judge
Open review pairs can go to an AI judge. It is asked the way a person would look: one variant, up to five candidates side by side with their pictures, "which one is the same item, if any?".
Its answer is checked in code before anything is done with it. Each reason must quote a field of both records, and every quote must appear in what the judge was shown. The judge merges a pair only when all of these hold:
- the choice is grounded: every quote was found;
- its confidence is at or above your auto-merge confidence;
- the pair has no decisive conflict;
- nobody undid a merge of the two before.
Any other answer leaves the pair open for people, with the judgement attached to read. Vendor text is data to the judge: a record that asks to be chosen still has to be chosen on quotes from both sides.
judgement.outcome | Meaning |
|---|---|
merged | Its choice was merged. |
offered | A grounded choice left to people; note says why. |
none | It found no match. |
ungrounded | A reason quoted what the records do not say. |
failed | It answered outside the expected form. |
Judge settings
Under Catalogue › Match review, the AI judge settings card (Edit), the same settings
as PATCH /v1/matching/judge-settings:
| Setting | Meaning |
|---|---|
enabled | Whether the judge looks at review pairs (Look at review pairs). On by default. |
daily_calls | Questions a day, at most (0 to 100,000). used_today counts the last 24 hours. |
auto_merge_confidence | Merge on its own: the judge's confidence (0.5 to 1) that merges a grounded choice; null sends every answer to people. |
model | The model asked; null for FurniOps' default. |
Reading the settings needs agent:read. Changing them needs agent:write (owners and admins),
which neither API keys nor OAuth apps can hold: a signed-in member changes them in the dashboard.
Each mode has its own.
4. People
Whatever no layer could decide waits in the review queue, best first. A person merges or dismisses each pair, and any merge, whoever made it, can be undone. See Review and merges.
What you see
A merge publishes product.merged and variant.merged; an undo publishes product.unmerged and
variant.unmerged. A merged ID keeps working: reads of it answer with the survivor. See
Master records.
Probes
Before adding a vendor, probe its site. A probe reads a URL politely and reports the platform with its evidence, any wall, the public feed, sitemaps, structured data coverage and the effort to pull it.
Review and merges
The pairs matching could not decide alone, and the merges it and your people made. Reading a pair's evidence and the AI judge's answer, merging or dismissing it, and undoing any merge.