Keep a local catalog fresh with updated_since

A headless storefront or a search index wants a local mirror of the catalog, not a live API call on every page view. Seed the mirror once, then keep it fresh cheaply: pull only what changed with updated_since, and skip unchanged pages with ETag revalidation. Pair it with webhooks for near-real-time updates between polls.

1. Seed the mirror (one full sync)

Page through the whole catalog once and upsert into your local store.

# Initial full sync - page through the whole catalog once.
curl -s "https://api.harmon.example/v1/products?page=1&page_size=100" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"

Record the newest updated_at you saw as your watermark - the next sync starts from there.

2. Pull deltas with updated_since

updated_since=<ISO-8601> returns only products changed since that instant - the efficient way to keep the mirror current between webhook deliveries. Advance your watermark to the newest updated_at in each batch.

# Only products changed since your last sync watermark.
curl -s "https://api.harmon.example/v1/products?updated_since=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"

Belt and braces

Subscribe to the product.updated and stock.changedwebhooks for push updates, and run an updated_since poll on a timer as a backstop in case a delivery is ever missed.

3. Revalidate with ETag / If-None-Match

Every list response carries a strong ETag. Send it back as If-None-Match and an unchanged page returns 304 Not Modified with no body - you keep your cached copy at almost zero cost.

# Revalidate a cached page: a 304 means "nothing changed", no body, no cost.
curl -s -i "https://api.harmon.example/v1/products?page=1&page_size=100" \
  -H "Authorization: Bearer hk_test_pub_your_key_here" \
  -H 'If-None-Match: "<etag-from-last-response>"'

Next steps

• Pagination & caching - the full ETag / If-None-Match / updated_since model.
• Verify a webhook - push updates to complement the poll.
• Render a product grid - serve the mirror you just built.

In the API Reference

Open this operation in the interactive reference (with a Try it console):

• GET /v1/products - supports updated_since, ETag, and If-None-Match