Skip to main content
GET
The price level and spread of a shelf.

Query Parameters

subject
string

What the question is about: an id (spt:, gpc:, brand:, retailer:, entity:) or a name. It is sent to the answering route as the parameter of its kind (an spt: id as spt, a brand: id as brand_id, a name as the route's name parameter), so send it OR that parameter, not both. Which kinds a split takes is in x-syntalic-presets; a kind it does not take is refused before anything is billed.

by
enum<string>
default:summary

How the answer is split. Each value is answered by one existing route; see x-syntalic-presets.

Available options:
summary,
distribution,
band,
brand,
product,
retailer
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. For analyst endpoints, supply either category or department; both may be supplied to narrow the scope.

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.

department
string

A Shopify taxonomy root, e.g. 'Electronics' or 'Food, Beverages & Tobacco'. Case-insensitive; matched against that root and nothing under it. A name that is not a root, including a retired browse department such as 'Grocery' or 'Home & Kitchen', is refused before payment and the response names the roots to send. For analyst endpoints, supply either category or department; both may be supplied to narrow the scope.

Minimum string length: 1
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
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}$
node
string

Ladder node as a Shopify taxonomy path, in slug or display form — 'electronics', 'electronics/computers', 'Electronics > Computers > Laptops', or a deeper rung. Required unless category is given.

brand
string

Optional. Locate one brand within the tiers: each tier gains brand_products, the count of that brand's products in it. Omit for the market view. A name that is nowhere in the catalog under that spelling is refused before payment, when the request arrives without payment attached (the normal 402 flow): a 404 whose error.details.alternates lists brands with a similar name (search them at /v1/public/brands?q=). A request that attaches payment up front is not checked and can still be billed for an empty answer, so send the unpaid request first or check the name at /v1/public/brands. A brand the catalog holds that has nothing for this request is still answered, with coverage.reason. A brand longer than 120 characters is a 400.

Minimum string length: 1
brand_id
string

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

Pattern: ^brand:b_[0-9a-f]{16}$
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
time_window
enum<string>

Historical window preset. Explicit from/to takes precedence and is reported as custom; time_window=custom requires both from and to. Date-only ranges use UTC calendar boundaries with inclusive from and exclusive to.

Available options:
last_30_days,
last_60_days,
last_90_days,
month_to_date,
previous_month,
month_over_month,
quarter_to_date,
custom
from
string<date>

Start date (ISO 8601, defaults to 30 days ago)

to
string<date>

End date (ISO 8601, defaults to now)

Response

The answer of the route that by selected, unchanged. The X-Syntalic-Preset response header names that route; its own path in this document has the response schema.

The response is of type object.