Prices at a store

Pull current shelf prices for one or more products at a specific store. The standard pattern for shopping apps, basket-pricing flows, and store-detail pages. Returns a tier-aware row per (store, product) pair so you always know whether the price came from this exact store, a sibling, or a chain fallback.

GET/v1/prices?store_id={id}$0.01

ℹ

Tier-aware lookup

When you ask for a store that hasn't been scraped (or that belongs to a chain with chain-wide pricing), the API resolves the request to the nearest sibling store in the same chain. The source_tier field tells you which path was taken — see "Tiered fallback" below.

Required pair: a store filter + a product filter

Every /v1/prices call needs at least one parameter from each side. For this workflow:

Store side (pick one)

Name	Type	Description
`store_id`	uuid	Single canonical store id. Triggers tier resolution if the store has no own scrape.
`store_ids`	string	Comma-separated UUIDs. Each one is resolved independently — useful for comparing 2-3 nearby stores in one call.

Product side (pick one)

Name	Type	Description
`q`	string	Trigram text search on product name + brand. Best when the user typed a query.
`barcode`	string	UPC or EAN, 6-32 digits.
`product_id`	uuid	Single canonical product UUID.
`product_ids`	string	Comma-separated UUIDs (cap 50). The basket-pricing path: hydrate every item in a shopping list with one call.

Workflow: price one product at one store

Request

curl 'https://api.mainmarket.com/v1/prices?store_id=8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10&barcode=00016000275287' \
  -H "Authorization: Bearer mm_live_..."

Workflow: price an entire shopping list at one store

The basket-pricing pattern. Pass up to 50 product UUIDs in one call to avoid N+1 round-trips. Each row is tier-aware, so you know which items have specific prices vs. fallback estimates.

Request

curl 'https://api.mainmarket.com/v1/prices?store_id=4f2a...&product_ids=9d4e...,a1b2...,c3d4...&limit=50' \
  -H "Authorization: Bearer mm_live_..."

Workflow: compare 2-3 stores side-by-side

Pass store_ids with a comma-separated list. The response includes per-store rows so you can show a side-by-side price comparison.

curlbash

curl 'https://api.mainmarket.com/v1/prices?store_ids=8c1a...,ee44...,ff55...&product_id=9d4e...&limit=10' \
  -H "Authorization: Bearer mm_live_..."

Sample response

200 OKjson

{
  "count": 3,
  "results": [
    {
      "product_id": "9d4e1c80-78a3-4a6d-9b1f-2cdb3d0c7e90",
      "name": "Cheerios Cereal, 18 oz",
      "brand": "Cheerios",
      "upc": "00016000275287",
      "store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
      "store_name": "Wegmans Brooklyn",
      "chain_slug": "wegmans",
      "price": 4.99,
      "regular_price": 5.49,
      "sale_price": 4.99,
      "is_on_sale": true,
      "unit_price": 0.28,
      "unit_price_uom": "oz",
      "aisle": "Aisle 4",
      "section": "Cereal",
      "available": true,
      "source_store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
      "source_store_name": "Wegmans Brooklyn",
      "source_tier": "specific",
      "source_distance_mi": 0.0,
      "pricing_scope": "per_store"
    }
  ]
}

Tiered fallback — what to do per tier

The most important field on a store-scoped query is source_tier. Treat each value differently:

specific: Surface the price without caveats. The store you asked about was scraped directly. source_distance_mi = 0.
regional: Disclose. Render with a "based on a nearby <chain>, X mi away" affordance. Common for chains that price uniformly within a metro but where this specific store hasn't been re-scraped recently.
chain: Authoritative for chains with pricing_scope = "chain_level" (Lidl, Trader Joe's, Aldi); a directional estimate for per_store chains. Always disclose the tier in your UI.

⚠

Don't sort regional + chain rows next to specific rows

If you're presenting a list of "cheapest nearby" results, filter to source_tier = "specific" before sorting by price. Mixing tiers produces phantom "cheapest" results that aren't actually purchasable at the named store.

Notable behavior

Soft-deleted store ids resolve transparently. If a Cart-app cache still holds an id from a pre-dedup canonical_store, the API maps it through store_id_redirects automatically — you'll get prices for the right store with no special handling.
aisle / section are populated when scraped. Pair with ?normalize_aisles=true to get the aisle in the same vocabulary as /v1/stores/{id}/aisles — useful for in-store route planning.
available signal. The latest scrape's stock signal — false when the chain reported the SKU as out-of-stock or de-listed at this store.

Errors

Name	Type	Description
`422`	Unprocessable Entity	Missing product or store filter, malformed UUID, or store_ids over 50.
`402`	Payment Required	Paid route — no payment proof.

Search prices — full endpoint reference.
Prices by UPC — flip the query: every store carrying one product.
Cheapest nearby — geo-scoped cheapest-by-product, no specific store id required.
Store aisles — pair with the aisle field for in-store routing.

Prices at a store

GET/v1/prices?store_id={id}$0.01

ℹ

Tier-aware lookup

Required pair: a store filter + a product filter

Every /v1/prices call needs at least one parameter from each side. For this workflow:

Store side (pick one)

Name	Type	Description
`store_id`	uuid	Single canonical store id. Triggers tier resolution if the store has no own scrape.
`store_ids`	string	Comma-separated UUIDs. Each one is resolved independently — useful for comparing 2-3 nearby stores in one call.

Product side (pick one)

Name	Type	Description
`q`	string	Trigram text search on product name + brand. Best when the user typed a query.
`barcode`	string	UPC or EAN, 6-32 digits.
`product_id`	uuid	Single canonical product UUID.
`product_ids`	string	Comma-separated UUIDs (cap 50). The basket-pricing path: hydrate every item in a shopping list with one call.

Workflow: price one product at one store

Request

curl 'https://api.mainmarket.com/v1/prices?store_id=8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10&barcode=00016000275287' \
  -H "Authorization: Bearer mm_live_..."

Workflow: price an entire shopping list at one store

The basket-pricing pattern. Pass up to 50 product UUIDs in one call to avoid N+1 round-trips. Each row is tier-aware, so you know which items have specific prices vs. fallback estimates.

Request

curl 'https://api.mainmarket.com/v1/prices?store_id=4f2a...&product_ids=9d4e...,a1b2...,c3d4...&limit=50' \
  -H "Authorization: Bearer mm_live_..."

Workflow: compare 2-3 stores side-by-side

Pass store_ids with a comma-separated list. The response includes per-store rows so you can show a side-by-side price comparison.

curlbash

curl 'https://api.mainmarket.com/v1/prices?store_ids=8c1a...,ee44...,ff55...&product_id=9d4e...&limit=10' \
  -H "Authorization: Bearer mm_live_..."

Sample response

200 OKjson

{
  "count": 3,
  "results": [
    {
      "product_id": "9d4e1c80-78a3-4a6d-9b1f-2cdb3d0c7e90",
      "name": "Cheerios Cereal, 18 oz",
      "brand": "Cheerios",
      "upc": "00016000275287",
      "store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
      "store_name": "Wegmans Brooklyn",
      "chain_slug": "wegmans",
      "price": 4.99,
      "regular_price": 5.49,
      "sale_price": 4.99,
      "is_on_sale": true,
      "unit_price": 0.28,
      "unit_price_uom": "oz",
      "aisle": "Aisle 4",
      "section": "Cereal",
      "available": true,
      "source_store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
      "source_store_name": "Wegmans Brooklyn",
      "source_tier": "specific",
      "source_distance_mi": 0.0,
      "pricing_scope": "per_store"
    }
  ]
}

Tiered fallback — what to do per tier

The most important field on a store-scoped query is source_tier. Treat each value differently:

specific: Surface the price without caveats. The store you asked about was scraped directly. source_distance_mi = 0.
regional: Disclose. Render with a "based on a nearby <chain>, X mi away" affordance. Common for chains that price uniformly within a metro but where this specific store hasn't been re-scraped recently.
chain: Authoritative for chains with pricing_scope = "chain_level" (Lidl, Trader Joe's, Aldi); a directional estimate for per_store chains. Always disclose the tier in your UI.

⚠

Don't sort regional + chain rows next to specific rows

Notable behavior

Soft-deleted store ids resolve transparently. If a Cart-app cache still holds an id from a pre-dedup canonical_store, the API maps it through store_id_redirects automatically — you'll get prices for the right store with no special handling.
aisle / section are populated when scraped. Pair with ?normalize_aisles=true to get the aisle in the same vocabulary as /v1/stores/{id}/aisles — useful for in-store route planning.
available signal. The latest scrape's stock signal — false when the chain reported the SKU as out-of-stock or de-listed at this store.

Errors

Name	Type	Description
`422`	Unprocessable Entity	Missing product or store filter, malformed UUID, or store_ids over 50.
`402`	Payment Required	Paid route — no payment proof.

Search prices — full endpoint reference.
Prices by UPC — flip the query: every store carrying one product.
Cheapest nearby — geo-scoped cheapest-by-product, no specific store id required.
Store aisles — pair with the aisle field for in-store routing.

Prices at a store

Required pair: a store filter + a product filter

Store side (pick one)

Product side (pick one)

Workflow: price one product at one store

Workflow: price an entire shopping list at one store

Workflow: compare 2-3 stores side-by-side

Sample response

Tiered fallback — what to do per tier

Notable behavior

Errors

Related

Prices at a store

Required pair: a store filter + a product filter

Store side (pick one)

Product side (pick one)

Workflow: price one product at one store

Workflow: price an entire shopping list at one store

Workflow: compare 2-3 stores side-by-side

Sample response

Tiered fallback — what to do per tier

Notable behavior

Errors

Related