Categories

Always filtered to status=1 — disabled categories are never returned. Disabled IDs respond 404.

If you need a hierarchical (nested) tree response, use Get Category Tree instead.

Endpoints

Method	Path	Purpose
GET	/api/shop/categories	Flat, paginated list of active categories
GET	/api/shop/categories/{id}	Single category by ID

Use the example switcher above the curl block to flip between the two.

Request Headers

Header	Required	Description
Accept	Yes	application/json
X-STOREFRONT-KEY	Yes	Storefront API key (pk_storefront_…)
X-Locale	No	Override request locale
X-Channel	No	Override channel scope

Query Parameters (collection only)

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
per_page	integer	15	Items per page. Max 100 for this endpoint.
parent_id	integer	—	Return only direct children of this category ID. Accepts parentId as alias.

Pagination headers (X-Total-Count, X-Page, X-Per-Page, X-Total-Pages) are emitted on the collection. See Pagination.

Category Object Fields

Both endpoints return the same shape — the collection wraps an array of these objects, the single endpoint returns one.

Field	Type	Description
id	integer	Category primary key
position	integer	Display order
status	boolean (0/1)	Always 1 on this endpoint
displayMode	string	products_and_description, products, or description_only
logoPath	string | null	Storage path to the category image
logoUrl	string | null	Fully-qualified image URL
url	string	Storefront URL for the category page
_lft, _rgt	integer	Nested-set tree pointers (internal; safe to ignore on the client)
createdAt, updatedAt	string (ISO-8601)	Timestamps
translation	object	Inline translation for the request locale (see below)
translations	array of IRI strings	All locale translations — GET <iri> to dereference
parent	string (IRI) | null	IRI to parent category. null for root categories
children	array	Inline child category objects (one level deep). Empty [] for leaves
filterableAttributes	array	Inline list of attributes flagged as filterable for this category

Inline translation fields

Field	Type	Description
id	integer	Translation primary key
categoryId	integer	Owning category ID
locale	string	Locale code (en, fr, de, …)
localeId	integer	Locale primary key
name	string	Localized category name
slug	string	URL slug (e.g. electronics)
urlPath	string	Full URL path including any parent slugs
description	string	HTML description shown on the category page
metaTitle	string	SEO <title> value
metaDescription	string	SEO meta description
metaKeywords	string	SEO meta keywords

See IRIs & HATEOAS for how to dereference the IRI fields.

Use Cases

• Render a flat category listing for a sidebar, footer, or admin search.
• Get all direct children of a parent (?parent_id=N) for a "subcategories" widget without traversing the whole tree.
• Read filterableAttributes to build a category-page faceted filter UI without an extra round trip.
• Walk up to the parent for breadcrumbs by following the parent IRI.
• Switch locales by following an entry in translations[] instead of re-issuing the request with a different X-Locale header.

Related Resources

• Get Category Tree — hierarchical tree response
• Get Products — pass ?category_id=N to filter by category
• Introduction → IRIs & HATEOAS