Products, Search & Categories

Visibility

GET /products — Public
GET /products/{slug} — Public
GET /search — Public
GET /product-categories — Public

Authentication

x-api-key: sk_eco_...

`GET /products`

Returns paginated product cards.

Query Parameters

Param	Type	Description
`limit`	`number`	Page size
`offset`	`number`	Pagination offset
`sort_by`	`string`	Sorting field
`sort_order`	`asc \| desc`	Sort direction
`min_price`	`number`	Minimum price filter
`max_price`	`number`	Maximum price filter
`category`	`string`	Category filter

Response Model

ProductListResponse with data[] and pagination.

`GET /products/{slug}`

Returns full product details including options, variants, collections, media, inventory, and SEO metadata.

Response Highlights

Field	Type	Description
`options`	`ProductOptionResponse[]`	Variant dimensions and available values
`variants`	`ProductVariantResponse[]`	Variant-level pricing, stock, option map
`price_range`	`{ min_price, max_price, currency }`	Computed price range
`collections`	`ProductCollectionBrief[]`	Related collection references
`images`	`ProductImageResponse[]`	Ordered media list

`GET /search`

Searches products by query text.

Query Parameters

Param	Type	Required	Description
`q`	`string`	Yes	Search query
`limit`	`number`	No	Result limit
`offset`	`number`	No	Pagination offset

Response

SearchResponse with data[], query, and pagination.

`GET /product-categories`

Returns active category labels used in storefront filtering/navigation.

cURL Examples

curl -X GET "https://api.ecommaps.com/api/v1/storefront/products?limit=12&offset=0" \
  -H "x-api-key: sk_eco_YOUR_KEY"
 
curl -X GET "https://api.ecommaps.com/api/v1/storefront/products/product-slug" \
  -H "x-api-key: sk_eco_YOUR_KEY"
 
curl -X GET "https://api.ecommaps.com/api/v1/storefront/search?q=shirt" \
  -H "x-api-key: sk_eco_YOUR_KEY"

SDK Example

const list = await ecommapsClient.products.list({ limit: 12, offset: 0 });
const detail = await ecommapsClient.products.retrieve("product-slug");
const search = await ecommapsClient.products.search("shirt", { limit: 10 });

Error Matrix

Status	Scenario
`400`	Invalid filters or malformed query
`401`	Missing/invalid API key
`404`	Product slug not found
`500`	Datastore/query failure

Store & Menus Collections