Skip to main content
GET
Price band and tiers for a category node

Query Parameters

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.

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.

category
string

The same as node, under the name every other category-scoped route uses. Send one of the two; sending both with different paths is a 400. A path, not a bare term: 'headphones' is refused.

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
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 node=, not with it.

Pattern: ^spt:[a-z]{2}(-[0-9]+)*$
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}$

Response

Price band

node
string
level
enum<string>
Available options:
root,
l2,
l3,
l4,
l5,
l6,
l7,
l8
products
integer

The shelf's products: served, with a current US price. The sum of the tiers.

pack_coverage
object

How much of this shelf states a pack. products is the same count as above. Prices here are still pack prices; this says how much of the shelf a per-unit comparison could cover.

price_range
object

Over the same products the tiers count.

band
object
tiers
object[]
coverage
object

How much data backed this answer. sufficient is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself. reason says why an answer is thin, empty or caveated, as a code from a closed set, and min is the floor products was judged against: branch on reason and phrase it in your own words. note says the same in English for a human reader.

resolved
object | null