Products API

The Products API is the public, read-only surface of the store catalog. It exposes only data that is already publicly readable per firestore.rules, reshaped into a stable PublicProduct wire format so native apps and other frontends can consume the catalog without depending on internal storage details.

There are two endpoints:

Both send a shared cache header (see Caching). Internal fields (such as the derived productNameLower search index) are stripped, and raw inventory counts are collapsed into an inStock flag so stock levels are never exposed.

GET /api/store/products

Public product listing and search. The endpoint has two mutually exclusive modes selected by the search param:

• Search mode — when search is present, it performs a name-prefix search and ignores category and cursor. Results are not paginated.
• List mode — otherwise, it returns a category-filterable, cursor-paginated page of the catalog.

Query parameters

Response

{
  "products": [
    {
      "id": "sku_1a2b3c",
      "productName": "Titan 9000 Hydraulic Pump",
      "brand": "Titan",
      "price": 1299.99,
      "categories": ["pumps", "hydraulics"],
      "description": "High-flow industrial hydraulic pump.",
      "primaryImageURL": "https://ecommerce-boilerplate.com/img/titan-9000.jpg",
      "pdfLink": "https://ecommerce-boilerplate.com/specs/titan-9000.pdf",
      "inStock": true
    }
  ],
  "nextCursor": "sku_1a2b3c",
  "totalCount": 128
}

Examples

curl "https://your-store.example.com/api/store/products?limit=2"

{
  "products": [
    { "id": "sku_a", "productName": "Alpha Widget", "brand": "Wavecrest", "price": 19.99, "categories": ["widgets"], "description": null, "primaryImageURL": null, "pdfLink": null, "inStock": true },
    { "id": "sku_b", "productName": "Beta Widget", "brand": "Wavecrest", "price": 24.99, "categories": ["widgets"], "description": null, "primaryImageURL": null, "pdfLink": null, "inStock": null }
  ],
  "nextCursor": "sku_b",
  "totalCount": 57
}

GET /api/store/products/{id}

Fetch a single public product by its catalog id.

Path parameters

Response

On success the body is a bare PublicProduct object — not wrapped in a products array.

curl "https://your-store.example.com/api/store/products/sku_1a2b3c"

{
  "id": "sku_1a2b3c",
  "productName": "Titan 9000 Hydraulic Pump",
  "brand": "Titan",
  "price": 1299.99,
  "categories": ["pumps", "hydraulics"],
  "description": "High-flow industrial hydraulic pump.",
  "primaryImageURL": "https://ecommerce-boilerplate.com/img/titan-9000.jpg",
  "pdfLink": "https://ecommerce-boilerplate.com/specs/titan-9000.pdf",
  "inStock": true
}

When no product has that id, the endpoint returns 404:

{ "error": "Product not found" }

PublicProduct schema

The public wire shape of a product. Every field is defensively narrowed from the internal record, so absent or malformed values become empty strings, empty arrays, or null rather than leaking internal shapes.

Caching

All three product responses (list, search, detail) send the same header:

Cache-Control: public, s-maxage=60, stale-while-revalidate=300

This value is defined once as PRODUCT_CACHE_CONTROL in src/lib/api/store.ts. It lets a CDN serve products from cache for 60 seconds and continue serving stale content for up to 5 minutes while revalidating in the background. The routes are dynamic, as every route handler is by default, so caching is delegated to that one shared header rather than to Next.js.

Error responses

Every error is a JSON object of the form { "error": "<message>" } with the appropriate status code (built by the shared jsonError helper).

{ "error": "Unknown category" }

Related