Products API

Browse the product catalog, filter, search, and retrieve variant details.

Base: /api/v1/products | X-Tenant-ID required | All endpoints public

GET /api/v1/products Public

List products with optional filtering, sorting, and pagination.

Query Parameters

Param	Type	Required	Description
`category`	string	No	Filter by category slug
`collection`	string	No	Filter by collection slug
`tags`	string	No	Comma-separated tag list
`minPrice`	number	No	Minimum base price
`maxPrice`	number	No	Maximum base price
`size`	string	No	Filter by variant size
`color`	string	No	Filter by variant color
`sort`	string	No	newest \| price_asc \| price_desc \| popular \| rating
`in_stock`	boolean	No	true = only in-stock products
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20)

Response

{
  "success": true,
  "data": { "products": [ { "id", "name", "slug", "base_price", "compare_price", "images", "category": { "id","name","slug" }, "tags" } ] },
  "meta": { "page": 1, "limit": 20, "total": 150, "total_pages": 8 }
}

GET /api/v1/products/featured Public

Shortcut to retrieve products where is_featured = true.

Response

{ "success": true, "data": { "products": [ ... ] } }

GET /api/v1/products/search Public

Full-text search across product names and descriptions.

Query Parameters

Param	Type	Required	Description
`q`	string	Yes	Search query string

Response

{ "success": true, "data": { "products": [ ... ] } }

GET /api/v1/products/:slug Public

Retrieve a single product by slug, including all active variants, review summary, and SEO fields.

Response

{
  "success": true,
  "data": {
    "product": {
      "id": "uuid", "name": "Classic Tee", "slug": "classic-tee",
      "description": "...", "base_price": 1500, "compare_price": 2000,
      "images": [ { "url": "...", "alt": "...", "is_primary": true } ],
      "category": { "id", "name", "slug" },
      "tags": ["summer"],
      "variants": [ { "id", "sku", "size", "color", "color_hex", "price_delta", "final_price": 1500, "stock": 12, "is_active": true } ],
      "review_summary": { "average": 4.3, "count": 27 },
      "seo": { "title": "...", "description": "...", "keywords": [] },
      "meta": {}
    }
  }
}

Possible Errors

Code	HTTP	When
NOT_FOUND	404	No product with that slug

GET /api/v1/products/:slug/reviews Public

Paginated list of approved reviews for a product.

Query Parameters

Param	Type	Required	Description
`page`	number	No	Page
`limit`	number	No	Per page

Response

{ "success": true, "data": { "reviews": [ { "id","rating","title","body","user":{"name"},"created_at" } ] }, "meta": { ... } }