Resolve a list

Map a list of free-text item names (or canonical UPCs) to retailer SKUs and PDP URLs at one specific store. Designed for the Cart WebView Send-to-Kroger / Send-to-Wegmans flow.

POST/v1/chains/{slug}/resolve-list$0.01

Path parameters

Name	Type	Description
`slug`required	string	Chain slug, e.g. `wegmans`.

Request body

Name	Type	Description
`store_id`required	uuid	Canonical store id where the list will be filled.
`items`required	ListItem[]	Up to 50 items. Each item below.

ListItem fields

Name	Type	Description
`client_id`required	string	Caller-supplied id echoed back on each result. Use to align response rows with your own list state.
`name`required	string	Free-text item name. 1–200 characters.
`canonical_product_id`	uuid	When supplied, skips fuzzy matching. The resolver uses this id directly and only falls back to fuzzy if the canonical has no SPP row at this store.

⚠

50-item cap

Requests with more than 50 items return 422 Unprocessable Entity. Batch large lists client-side; each batch is one billed call.

Request

curl -X POST 'https://api.mainmarket.com/v1/chains/wegmans/resolve-list' \
  -H 'Content-Type: application/json' \
  -d '{
  "store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
  "items": [
    { "client_id": "row-1", "name": "Whole milk gallon" },
    { "client_id": "row-2", "name": "Eggs cage free dozen" },
    { "client_id": "row-3", "name": "Cheerios", "canonical_product_id": "9d4e..." }
  ]
}'

Response

200 OKjson

{
  "store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
  "items": [
    {
      "client_id": "row-1",
      "resolved": true,
      "canonical_product_id": "1a2b...",
      "upc": "00071600051501",
      "retailer_product_id": "0021",
      "pdp_url": "https://shop.wegmans.com/product/0021",
      "in_stock": true,
      "price": 4.49,
      "sale_price": null,
      "on_sale": false,
      "match_method": "fuzzy_name",
      "matched_name": "Wegmans Whole Milk, Gallon",
      "match_confidence": 0.92
    },
    {
      "client_id": "row-2",
      "resolved": true,
      "canonical_product_id": "3c4d...",
      "upc": "00072100170012",
      "retailer_product_id": "0144",
      "pdp_url": "https://shop.wegmans.com/product/0144",
      "in_stock": true,
      "price": 6.99,
      "sale_price": 5.99,
      "on_sale": true,
      "match_method": "fuzzy_name",
      "matched_name": "Vital Farms Cage Free Large Eggs, Dozen",
      "match_confidence": 0.87
    },
    {
      "client_id": "row-3",
      "resolved": true,
      "canonical_product_id": "9d4e...",
      "upc": "00016000275287",
      "retailer_product_id": "0091",
      "pdp_url": "https://shop.wegmans.com/product/0091",
      "in_stock": true,
      "price": 5.49,
      "sale_price": null,
      "on_sale": false,
      "match_method": "canonical_id",
      "matched_name": "Cheerios Cereal, 18 oz",
      "match_confidence": 1.0
    }
  ]
}

ResolvedItem fields

Name	Type	Description
`client_id`	string	Echo of the request's client_id.
`resolved`	boolean	True when a candidate matched. False when no match cleared the confidence floor.
`canonical_product_id`	uuid \| null	Matched canonical product id. Null when not resolved.
`upc`	string \| null	GS1 UPC of the matched product.
`retailer_product_id`	string \| null	Chain's own SKU at this store. Use for cart-add deep links.
`pdp_url`	string \| null	Direct PDP URL at the chain's storefront.
`in_stock`	boolean \| null	Stock signal from the latest scrape; null when the chain doesn't expose stock.
`price, sale_price`	number \| null	Effective and sale prices. price reflects the rung the customer would actually pay.
`on_sale`	boolean	True when sale_price is set and lower than the regular price.
`match_method`	string	How the row matched: `canonical_id` when the caller supplied a canonical_product_id and it was found, otherwise `fuzzy_name`.
`matched_name`	string \| null	The canonical product name that matched, for UI confirmation.
`match_confidence`	number	0.0–1.0. `canonical_id` matches return 1.0; `fuzzy_name` returns the pg_trgm similarity score (floor 0.3).

Notable behavior

Fuzzy matching uses Postgres pg_trgm with a similarity floor of 0.3. Below that floor the row returns resolved: false.
When a canonical match has no SPP row at the requested store, the resolver falls back to a chain-sibling lookup (same provenance tiering as /v1/prices) and surfaces those prices.
The response order matches the request order. Use client_id as the source of truth for alignment instead of array position.
Each call costs $0.01 regardless of how many items it contains (up to the 50-item cap).

Errors

Name	Type	Description
`404`	Not Found	Slug is not a known chain, or store_id does not exist on that chain.
`422`	Unprocessable Entity	More than 50 items, missing required field, or store_id does not belong to the requested chain.
`402`	Payment Required	Paid route — no payment proof.