TutorialsShow a product catalog

Show a product catalog

Build a listing page and a product-detail page (PDP) from the public catalog endpoints. These are public reads — they work with pk_test_* in the browser or with the x-tenant-slug header server-side.

1. List products

curl "https://api-test.theorchard.dev/api/v1/products?limit=24" \
  -H "Authorization: Bearer pk_test_your_key"
{
  "products": [
    {
      "id": "0191...a1",
      "name": "Coldbrew Concentrate",
      "slug": "coldbrew-concentrate",
      "price": { "amount": 1800, "currency": "usd" },
      "first_image_url": "https://.../coldbrew.jpg"
    }
  ],
  "cursor": "eyJ..."
}
  • Paginate with the cursor from the response: ?cursor=<cursor>.
  • Search with ?search=coldbrew.
  • Batch-fetch specific products with ?ids=a,b,c (max 100 UUIDs).
// A minimal listing component (React)
async function loadProducts(cursor) {
  const url = new URL('https://api-test.theorchard.dev/api/v1/products');
  url.searchParams.set('limit', '24');
  if (cursor) url.searchParams.set('cursor', cursor);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.NEXT_PUBLIC_ORCHARD_PK}` },
  });
  return res.json(); // { products, cursor }
}

2. Product detail (PDP)

Fetch one product by its slug, plus its images and reviews:

# the product
curl https://api-test.theorchard.dev/api/v1/products/coldbrew-concentrate \
  -H "Authorization: Bearer pk_test_your_key"
 
# ordered images
curl https://api-test.theorchard.dev/api/v1/products/coldbrew-concentrate/images \
  -H "Authorization: Bearer pk_test_your_key"
 
# reviews
curl https://api-test.theorchard.dev/api/v1/products/coldbrew-concentrate/reviews \
  -H "Authorization: Bearer pk_test_your_key"

The product carries a metadata JSON object for category-specific fields (flow rate, dimensions, spec-sheet links — whatever your store models) — render the keys you care about.

3. Show stock without leaking counts

Don’t expose raw inventory. Ask for a coarse status for the products on the page:

curl -X POST https://api-test.theorchard.dev/api/v1/inventory/status \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["0191...a1", "0191...a2"] }'

Returns in_stock / low_stock / out_of_stock per product — enough to show an “Only a few left” badge or disable the buy button, with no count disclosure.

Money formatting

Prices are integer minor units + currency. Format on the client:

const fmt = (price) =>
  new Intl.NumberFormat('en-US', { style: 'currency', currency: price.currency })
    .format(price.amount / 100); // 1800 → "$18.00"

Next

OverviewCart to checkout to order