Kroger API endpoint
Browses a Kroger product category and returns product cards plus facet groups, in the same shape as kroger-search. slug and category_id together identify the category (e.g. "pet" and "27" for kroger.com/pl/pet/27) -- call kroger-categories to discover every valid slug/category_id pair. It uses category_id as a taxonomy filter, with real pagination, and the source field reports which path answered. Facet filters and sort apply to the primary path only: when any of them is set, a failure of that path returns an error rather than silently falling back to unfiltered results.
/kroger/categoryQuery parameters:
slug (required) — the category's URL slug segment (e.g. pet from
kroger.com/pl/pet/27). Unlike Kroger product pages, a placeholder slug
is not confirmed to work here, so the real slug must be supplied. Discover
every valid slug/category_id pair from
kroger-categories.category_id (required) — the category's numeric taxonomy id, the last
path segment of its category page URL (e.g. 27). See
kroger-categories for the full list.page (optional) — one-based result page, default 1.Facet filters and sort (all optional, JSON path only — see below):
sort — result order. One of relevance (default), name_asc,
popularity_desc. Any other value returns 400 before any upstream
request is made.brands — comma-separated brand names, e.g. Halo Top,Rebel.nutrition — comma-separated nutrition/dietary facet values, e.g.
Gluten Free.flavor — comma-separated flavor facet values, e.g. Chocolate.scent — comma-separated scent facet values, e.g. Bergamot.savings — comma-separated savings facet values. On Sale is the
confirmed value.more_options — comma-separated more-options facet values. Confirmed
values: SNAP EBT Eligible, In-Stock Items Only.price_min / price_max — price bounds. price_max is required to
filter on price at all; price_min defaults to 0 (an "under $N"
filter). Supplying price_min alone returns 400.Filter values are facet names, taken verbatim from a previous
response's facets[].values[].name — Kroger filters on the display name,
not the slug. Multiple values within one filter are OR-ed together.
Notable response behavior:
Filters and sort apply to the json_api path only. When any of them
is set and that path fails, the request returns an error instead of
falling back to the rendered page — the HTML path cannot honor these
filters, so returning its unfiltered results would be wrong. Unfiltered
requests still fall back as before.
Each result's upc is usable directly as the upc query parameter to
/kroger/product.
total_count is Kroger's own count of matching products on the
json_api path. On the html fallback it reflects only what that page
reported as loaded.
source, has_more, facets, brand and stock_level behave exactly
as documented for /kroger/search — the two endpoints
share one implementation, with category_id sent as a taxonomy filter
instead of a keyword query.
Pagination is real on the json_api path; on the html fallback it
remains best-effort.
A missing slug or category_id returns 400 before any upstream
request is made.
| Field | Filled in, of 32 checked | Values in the sample |
|---|---|---|
| upc | 32 | |
| url | 32 | kroger.com |
| title | 32 | “Fancy Feast Chicken in Chicken Gravy Wet Cat Food” and 31 other values |
| image_url | 32 | kroger.com |
| price | 32 | 0 |
| currency | 32 | USD in all 32 |
| unit_price | 32 | “$0.33/oz” and 10 other values |
| size | 32 | “3 oz.” and 11 other values |
| snap_ebt_eligible | 32 | true in 0 of 32 |
| low_stock | 32 | true in 1 of 32 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| slug | string | Yes | Category URL slug segment. Obtain valid slug/category_id pairs from kroger-categories | pet | |
| category_id | string | Yes | Category numeric taxonomy id. Obtain valid slug/category_id pairs from kroger-categories | 27 | |
| page | integer | No | One-based result page Minimum: 1. | ||
| sort | string | No | Result order. One of: relevance, name_asc, popularity_desc Allowed values: relevance, name_asc, popularity_desc. | ||
| brands | string | No | Comma-separated brand names to filter by, taken verbatim from a previous response's facets | Halo Top,Rebel | |
| nutrition | string | No | Comma-separated nutrition/dietary facet values | Gluten Free | |
| flavor | string | No | Comma-separated flavor facet values | Chocolate | |
| scent | string | No | Comma-separated scent facet values | Bergamot | |
| savings | string | No | Comma-separated savings facet values | On Sale | |
| more_options | string | No | Comma-separated more-options facet values | SNAP EBT Eligible | |
| price_min | number | No | 0 | Lower bound of the price filter; defaults to 0 | 0 |
| price_max | number | No | Upper bound of the price filter; required to filter on price | 8 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/kroger/category?slug=pet&category_id=27&page=1&sort=relevance" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"slug": "mushrooms",
"category_id": "0611200686",
"page": 1,
"total_count": 28,
"products": [
{
"upc": "0001111091487",
"url": "https://www.kroger.com/p/sliced-white-mushrooms/0001111091487",
"title": "Sliced White Mushrooms",
"image_url": "https://www.kroger.com/product/images/medium/front/0001111091487",
"price": 2.39,
"currency": "USD",
"size": "8 oz",
"snap_ebt_eligible": true,
"low_stock": false
}
]
}
}Request schema
No body schema
Response schema
#/definitions/kroger.categoryResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | kroger.CategoryResponse | No | ||||
| data.category_id | string | No | ||||
| data.facets | array | No | SearchFacetGroup record, 5 fields: group, values. Described under Kroger search API. | |||
| data.has_more | boolean | No | HasMore, Source and Facets carry the same meaning as on SearchResponse -- see that type and Search's doc comment. | |||
| data.page | integer | No | ||||
| data.products | array | No | SearchResultProduct record, 13 fields: brand, currency, image_url, low_stock, original_price, price, size, snap_ebt_eligible, stock_level, title, unit_price, upc and 1 more. Described under Kroger search API. | |||
| data.slug | string | No | ||||
| data.source | string | No | ||||
| data.total_count | integer | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/kroger/category?slug=pet&category_id=27&page=1&sort=relevance" \
-H "x-api-key: $CRAWLORA_API_KEY"