Products (storefront API)

Storefront and customer routes of the products module. Send Accept-Language (or X-Locale from a browser) on every call; a customer route needs the session cookie.

GET /v1/products

List active products

Parameters:

• brand in query (string, optional).
• categoryId in query (string, optional).
• ids in query (string, optional).
• isFeatured in query (boolean, optional).
• maxPrice in query (number, min 0, optional).
• minPrice in query (number, min 0, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, max 100, optional).
• sortBy in query (string, optional).
• sortOrder in query ("asc", "desc", optional).
• specs in query (string, pattern ^[a-z0-9-]+:[a-z0-9-]+(,[a-z0-9-]+:[a-z0-9-]+)*$, max length 1024, optional).
• tags in query (string, pattern ^[a-z0-9-]+:[a-z0-9-]+(,[a-z0-9-]+:[a-z0-9-]+)*$, max length 512, optional).

Responses:

• 200: Products retrieved.
• 400: Invalid query parameters.

GET /v1/products/{slug}

Get product by slug

Parameters:

• slug in path (string, required).

Responses:

• 200: Product retrieved.
• 404: Product not found.

GET /v1/products/{slug}/questions

List product questions

Parameters:

• slug in path (string, required).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, max 100, optional).

Responses:

• 200: Questions retrieved.
• 404: Product not found.

POST /v1/products/{slug}/questions

Create product question

Parameters:

• slug in path (string, required).

Request body: CreateQuestionDto.

Responses:

• 201: Question created.
• 400: Invalid input.
• 401: Unauthorized.
• 404: Product not found.

GET /v1/products/{slug}/reviews

List product reviews

Parameters:

• slug in path (string, required).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, max 100, optional).
• rating in query (number, min 1, max 5, optional).
• sortBy in query ("createdAt", "helpfulCount", "rating", optional).
• sortOrder in query ("asc", "desc", optional).

Responses:

• 200: Reviews retrieved.
• 404: Product not found.

POST /v1/products/{slug}/reviews

Create product review

Parameters:

• slug in path (string, required).

Request body: CreateReviewDto.

Responses:

• 201: Review created.
• 400: Invalid input.
• 401: Unauthorized.
• 404: Product not found.

GET /v1/products/{slug}/reviews/eligibility

Whether the caller may review this product

Parameters:

• slug in path (string, required).

Responses:

• 200: Eligibility resolved.
• 401: Authentication required.
• 404: Product not found.

GET /v1/products/{slug}/reviews/mine

Get the caller’s own review for a product

Parameters:

• slug in path (string, required).

Responses:

• 200: Own review retrieved (null when none).
• 401: Authentication required.
• 404: Product not found.

GET /v1/products/{slug}/reviews/summary

Get review summary

Parameters:

• slug in path (string, required).

Responses:

• 200: Summary retrieved.
• 404: Product not found.

GET /v1/products/brands

List brand facets for the catalogue

Parameters:

• categoryId in query (string, max length 64, optional).

Responses:

• 200: Brand facets retrieved.
• 400: Invalid query parameters.

GET /v1/products/spec-facets

List filterable specification facets

Responses:

• 200: Facets retrieved.

Schemas

CreateQuestionDto

• question (string, max length 1000, required).

CreateReviewDto

• rating (number, min 1, max 5, required).
• title (string, max length 200, optional).
• body (string, max length 5000, required).
• assetIds (array of string, uuid, optional).