API Reference Overview

The boilerplate exposes two distinct API families, plus a handful of optional, feature-gated endpoints. Understanding which family you are talking to is the key to using the API correctly:

• The Store REST API (/api/store/*) is a public, read-only, cache-friendly view of the catalog. It is meant for external clients — native apps, alternate frontends, integrations — that need to read products and categories without touching internal storage details.
• The Commerce RPC API (/api/commerce/*) is the authenticated backend the app itself calls when it runs on a SQL backend (Postgres/Prisma or Supabase). It is an internal transport, not a public API, and every non-public method requires a Firebase ID token.

The two API families

Store REST API

The Store API reshapes data that is already publicly readable (products, categories) into a stable wire format so callers never depend on internal storage details. Inventory counts, for example, are collapsed into an inStock flag so exact stock levels are never exposed.

GET /api/store is a discovery document that lists the available endpoints and the API version:

curl https://your-store.example.com/api/store

{
  "name": "Your Store",
  "version": "v1",
  "endpoints": [
    "/api/store/products",
    "/api/store/products/{id}",
    "/api/store/categories"
  ]
}

Key characteristics:

• Read-only. Every endpoint is a GET. There are no public write paths.
• Cursor pagination. GET /api/store/products returns { products, nextCursor, totalCount }; pass the returned nextCursor back as ?cursor= to page forward. See Store: Products.
• CDN cache headers. Responses carry a public Cache-Control header so a CDN or the browser can cache them (details below).
• Stable wire shape. Products are returned as a narrowed PublicProduct (id, productName, brand, price, categories, description, primaryImageURL, pdfLink, inStock).

Commerce RPC API

POST /api/commerce/<service>/<method> is an RPC-style bridge from the client to a server-side commerce adapter. The client posts one request per commerce call:

POST /api/commerce/products/list
Authorization: Bearer <firebase-id-token>
Content-Type: application/json

{ "args": [] }

and receives { "result": <return value> }, or { "error": string } with a 4xx/5xx status. Dates in the result serialize to ISO strings and are revived by the client.

Access levels

Firebase Auth is the identity provider. Each whitelisted method carries one of three access levels:

quotes.submit is the one exception to the user rule: it allows a null userId for guest submissions (no token needed then), but a non-null userId must still match the token.

A method that is not on the whitelist responds 404, indistinguishable from a non-existent route. See Commerce RPC for the full whitelist and per-service argument shapes.

Optional feature endpoints

These endpoints back optional, env-gated features. They keep working as no-ops (or return 503) when their integration is not configured, so the default quote-based store runs without any of them.

See environment variables for the flags that switch these on.

Common error shape

Both API families return errors as a single JSON object:

{ "error": "Human-readable message" }

The Store API uses jsonError(status, message) and the Commerce RPC route uses an equivalent error(message, status) helper, so the shape is identical across the surface. Request data is never echoed back in error messages.

Standard status codes

Cache-Control policies

The Store API sets one of two Cache-Control headers depending on how quickly the underlying data changes. Both are defined in src/lib/api/store.ts:

/** Cache-Control for product endpoints (list, search, detail). */
export const PRODUCT_CACHE_CONTROL =
  "public, s-maxage=60, stale-while-revalidate=300";

/** Cache-Control for slow-changing config-backed endpoints (categories). */
export const CONFIG_CACHE_CONTROL =
  "public, s-maxage=3600, stale-while-revalidate=86400";

s-maxage is the shared-cache (CDN) freshness window in seconds; stale-while-revalidate lets a CDN serve stale content for that many additional seconds while it revalidates in the background. Products stay fresh for 60s; category and config data, which changes rarely, for an hour.

Explore the endpoints