---
title: "Product identity rules · Nook docs"
canonical: https://www.checkoutbench.ai/docs/product-identity
last_updated: 2026-11-03
---

# Product identity rules

> As of Nov 3, 2026, 2:45 PM PST, from Nook main 680daa2f.

Nook must be sure the thing in the checkout is the exact product the person chose: same item, same size or kit, same pack count. If it can't prove that, it blocks with `product_mismatch` instead of quoting. This page explains the Amazon rules in plain words.

## The basic rule

- The product the person picks is identified by Amazon's own product ID (the ASIN). After a person picks from listings, the agent sends that ID as the item's `product_id`.
- At checkout, Nook compares each checkout line against the chosen product. The old comparison accepted only an exact (normalized) title match, or one known brand-name prefix.
- Images, price and a model's confidence are never accepted as proof of identity on their own.

## The problem found on Oct 25

- On some products, the product page shows a **short heading**, but the checkout shows a **longer title** (the same words plus extra descriptive text).
- In those checkouts, Nook could not read a product ID either.
- So a correct product failed the exact title match and was blocked as `product_mismatch`. Trying again could not help, because the rule is deterministic.

## The fix (PR #158): one source-bound "title alias"

When Nook reads the chosen product's page, it may record **one** extra exact title, called a title alias, taken from the page's own document title. It does this only if all of these hold:

1. The page address, the page's canonical address, and the page's Buy Now and Add to cart forms all name the same chosen product ID. The canonical address can be a `/dp/` or a `/clp/` link, and all of them must be on amazon.com.
2. The document title has Amazon's usual site wrapper and starts with the visible heading, extending it at Amazon's ` | ` separator. The whole title is at most 1,000 characters.
3. The heading is actually visible on the page. A hidden heading cannot create an alias.

If any of these fail (a title that is too long, a parent product instead of the exact variant, a conflicting Buy form, a different host, an unrelated title), no alias is recorded and the old rule applies.

At checkout:

- A checkout line matches if its title equals the alias exactly (after normalizing), **and** the checkout's product IDs are either missing or agree with the chosen product.
- A checkout ID that points to a different product still blocks.
- Nook may also read product IDs from checkout links that belong to the product's title.
- If the visible title already shows a different amount or count, that mismatch is checked first, so the longer alias can't hide it.
- Quantity, seller, charges, address and card checks are unchanged and still have to pass.
- One older rule uses price: when a checkout line shows the chosen product's exact title and exact price, a different checkout ID is still accepted, because Amazon files some multipacks under the single item's ID. This rule does not apply to aliases.
- A checkout ID that is another option on the same product page, at the checkout's price, blocks.

## What is never accepted

- A fuzzy or partial title match ("starts with roughly the same words").
- An image match.
- A price match on its own.
- A model saying it is confident.

## Status

- Merged to Nook main (merge commit `8ca92315`, Oct 25, 9:33 PM PDT) and released to production the same night at 9:52 PM PDT. The release checks passed: the cloud and service tests and one live Amazon quote.
- Follow-up released Oct 26 (PR #164): a `/clp/` canonical link can record the alias too.
- Proof: quote-only runs on a test account. The $87.10 DJI quote was complete for the product that had been blocked, matched the requested address and card and put the cart back. Nine identity tests cover the rule.
- Not yet shown: a production quote that needed an alias.

## Other Amazon behaviour

- When the request is general, Nook picks the cheapest product that fits from what Amazon's search shows. It opens up to three of the products it picks and reads each page's own options, such as color or size, and may switch to an option the page shows before anything goes in the cart. When none fits, it returns `product_choice_requires_user` with `choices` and `listings`, so the person can pick.
- The quote names the option Amazon actually selected in `items[].selected_variants`. A purchase reopens that exact product and option and never searches again. If Amazon changed the selected option before the cart action, Nook blocks with `product_changed`.
- Nook checks out only its own lines and leaves anything else in the person's cart alone.
- When Amazon shows its optional paid protection offer after Add, Nook declines it once, only for the selected product. No paid add-on is accepted (released Oct 2).

## Other stores

- The identity rules at Walmart, Target, Chewy, Instacart and Uber Eats have not changed since Oct 25. Target's reader now names search results by their brand and product name.
- A store Nook set up from its web address identifies a product by its page path (ignoring the query string) and matches cart lines by that path or the exact name.