Skip to main content
GET
View all products and pricing in a category

Query Parameters

category
string

Product category in the Shopify product taxonomy. Accepts a display path (e.g. 'Electronics > Computers > Laptops'), its slug form (e.g. 'electronics/computers/laptops'), a single path segment (e.g. 'laptops', 'headphones'), or an everyday shelf name (e.g. 'apparel', 'beauty', 'grocery'); matched against the catalog's category tree (exact node, subtree, or whole path segment). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. Some product types are filed under more than one department (e.g. Protein Bars under both Food and Health & Beauty); add include_homes=true to read every home of such a type as one shelf.

Minimum string length: 1
include_homes
boolean
default:false

Optional. true reads a product type filed under more than one department (e.g. Protein Bars under both Food and Health & Beauty) as one shelf, every home included. Absent or false: the shelf the category names, and nothing else.

country
enum<string>
default:us

Country (us or ca)

Available options:
us,
ca
retailer
enum<string>

Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)

Available options:
amazon,
walmart,
target,
bestbuy,
homedepot,
costco,
ikea,
samsclub,
cvs,
dillards
sort_by
enum<string>
default:representative

Sort order. Default representative: nearest the category mean. price_asc and price_desc are explicit. rating and reviews are accepted for compatibility and fall back to representative.

Available options:
representative,
price_asc,
price_desc,
rating,
reviews
cursor
integer

Pagination cursor — pass the previous response's next_cursor

Required range: x >= 0
limit
integer
default:20

Max results to return (default 20, min 1, max 50)

Required range: 1 <= x <= 50
publish_id
string

Optional. Pin the answer to a serving publish: pass meta.publish_id from an earlier answer. When the served snapshot has moved on, or cannot be confirmed, the request is answered 409 PUBLISH_CHANGED naming the current publish, before any payment challenge and free. Use it to keep several answers on one snapshot.

Minimum string length: 1
spt
string

A shelf by id, from GET /v1/ontology/resolve (a category match's id). Send it instead of category=, not with it.

Pattern: ^spt:[a-z]{2}(-[0-9]+)*$
gpc
string

A product type by GS1 GPC id, from GET /v1/ontology/resolve (a product_type match's id). Covers EVERY shelf the type is filed under, so a type shelved in two departments is one scope (category=<8 digits> filters by browse-node placement). Send it instead of category= or spt=, not with them.

Pattern: ^gpc:[0-9]{8}$
retailer_id
string

A chain by id, from GET /v1/ontology/resolve (a retailer match's id): the chain (seller_norm) whatever lane its listings were scraped through, never a lane. retailer= matches the scrape lane, so a Shopify store's chain can only be asked for by id (#1090). Send it instead of retailer=, not with it.

Pattern: ^retailer:[a-z0-9]{1,64}$

Response

Competitive landscape

category
string
country
string
currency
string
items
object[]
stale_offers
integer | null

How many of the category's offers (all pages, not only this one) are not current offers; null on a page past the end. An offer is not current when its last reading said out of stock and that reading is older than its listing's own window: 1.5 times how often we refresh that listing, and never less than 7 days (30 days for a listing with no refresh cadence); Shopify and Google Shopping listings are not judged by that rule. Nor is it current, in stock or not, when its price was observed more than 30 days ago and its retailer's feed (the lane and the chain: a Shopify store is its own) has had no price read in 30 days; a live retailer's older offers keep the rule above. A stale offer is shown, flagged current: false and stale: true with its last_seen_at date and a price_note ("last seen 2026-07-14"), and sorted after the current offers; it is left out of every price statistic and counted in stale_offers.

next_cursor
integer | null
has_more
boolean
resolved
object
meta
object