Skip to main content
The checked-in Go API and OpenAPI define the canonical public catalog reads below. The Convex projection code and its five-minute cron are implemented locally, but they are not evidence that a deployment has the approved catalog origin configured or that the cron has been deployed.
Batch Relay’s Go catalog is the only owner of canonical product IDs, revisions, prepared-artwork requirements, provider-neutral lifecycle state, verified unit costs, provider offers, and offer pricing revisions. The public API publishes that data through GET /v1/catalog/products and GET /v1/catalog/products/{product_id}/offers. The canonical source is the Go catalog exposed by one public API/OpenAPI surface:
/products returns active immutable products and an ETag; /offers returns published provider offers, configuration, availability, verified unit costs, and pricing revisions without exposing provider-native SKU/UID values. Quotes and orders use a concrete product ID and revision. Convex may keep a read projection in canonicalProducts for indexed storefront, editor, package, checkout, and image-preflight reads. It must not become a second fulfillment catalog or cost table. Studio retail prices remain studio-owned Convex data.

​
Revision and conditional refresh

The local projection records the last successful checksum/source origin, active item count, and synchronization time. Its internal cron is scheduled every five minutes and checks the deployment-owned Go API origin with If-None-Match. That schedule remains inactive until the Convex deployment has BATCH_RELAY_CATALOG_API_BASE_URL configured and the code/cron is deployed.
  • 304 Not Modified writes nothing.
  • An unchanged checksum writes nothing.
  • A changed revision upserts active products idempotently.
  • Products absent from an active upstream list are removed from new pickers but historical revisions and order evidence remain readable.
  • A malformed or partial response preserves the last good projection and raises an operations alert.
Any web-app “Fetch products from Batch Relay API” control is a recovery tool only once its adapter is configured and deployed. Its result should state whether the projection changed and identify the upstream ETag/checksum.

​
ETag recovery semantics

Treat an ETag as an opaque validator. Do not construct it, compare it as a version number, or persist a partially fetched replacement catalog. On a timeout, validation failure, or non-success response, retain the prior ETag and last-good projection. Retry the next scheduled pass or use the recovery control after correcting the upstream problem.

​
Provider status

RPL is deferred and unknown. A product, offer, price, availability result, or canary must not imply that RPL is ready until Batch Relay has verified its catalog and executor.