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. Approved pricebook versions supply provider offers and their 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. Protected staff reads project approved pricebook offers with the exact product revision, configuration, provider, environment, units per quantity, and standard or account scope. Account overrides take precedence over standard rows. A missing row means no approved cost. Canonical product metadata and public default offers cannot supply a fallback for these protected reads.