Build a product catalogue

Use v2 listing endpoints for browsing, then fetch long detail only when a customer opens a product or begins checkout.

Recommended flow

1. Load filter values

   Fetch brands, categories, and departments for selectors.

2. List products

   Request a small first page and paginate on demand.

3. Search when typed

   Debounce input and call searchProducts.

4. Open detail

   Call getLongProduct with the selected ID.

Pagination

Pages start at 1. The default page size is 10 and v2 caps it at 100. Continue while hasNextpage is true. An empty out-of-range page can return HTTP 200 with an empty data array and a failure-style status message, so key UI behavior off the array rather than the status text alone.

Filters and sorting

Send comma-separated values for brandFilter, categoryFilter, familyFilter, and departmentFilter. Supported sort fields are price, brand, category, family, department, name, and onSale.

Search

Search uses Typesense to identify IDs, then hydrates results from Shioja's versioned catalogue. The response therefore retains the same product shape and app-specific pricing as regular listings.

Details and batch reads

getLongProduct reads canonical product detail and rejects out-of-stock products. getManyProducts accepts comma-separated IDs and is suitable for carts, wishlists, and server-side reconciliation.

Caching

List responses include X-Shioja-Catalog-Version. Store it with cached data and invalidate when the product manifest version changes. Do not cache availability indefinitely; re-read detail and create a fresh quote before ordering.