Skip to Content

ORBCATALOG DOCUMENTATION

HTTP API

Every public read of the catalog, how long each is cached and what purges it.

Read from a storefront

A storefront Worker in the same Cloudflare account can bind to Catalog's Storefront entrypoint. Bind to the Catalog Worker for that environment:

{
  "services": [{ "binding": "CATALOG", "service": "orbcatalog", "entrypoint": "Storefront" }],
}

Use the Catalog client's fetch option to send each request to env.CATALOG.fetch(request) instead of the network. The binding serves the public delivery reads and uses Workers Cache, without the per-address miss budget. Catalog sends publish purges to both the public and Storefront caches. The binding cannot reach staff, Source or change-feed routes.

Browsers, storefronts outside Workers and Workers in another Cloudflare account use the public Catalog URL. Cache misses on that URL still count towards the route's per-address budget.

Routes and cache lifetimes

The table shows standard lifetimes. An answer showing any limited offer is fresh for 10 seconds, with a 5-second revalidation window and up to one day of stale-if-error. Supplying channel to a listing or product find includes prices and uses the shorter offer lifetime.

RouteWhatCache (browser / edge)Tags
GET /v1/products/{ref}?locale=&fallback=defaultPublished base data, one locale, no Channel; urls by Channelmax-age=60 / edge max-age=600, both stale-while-revalidate=600, stale-if-error=86400p:{h(ref)}, e: of each entry it links, catalog
GET /v1/products?category=&locale=&limit=&after=Cards of a category, pinned first, then newest60 / 600c:{h(category)}, e: of each entry a card links, catalog
GET /v1/categories/{ref+}?locale=&fallback=default, GET /v1/categories?parent=&locale=A category with its path to the root and whether it hasChildren in the locale, the tree in position order; a ref may hold slashes (outdoor/rucksaecke)60 / 600c:{h(ref)} of every category shown, ancestors included; roots for the roots; catalog
GET /v1/registers/{register}/entries/{ref}?locale=&fallback=default, GET /v1/registers/{register}/entries?locale=&limit=&after=An entry of a register, such as a brand, and a register's entries by name60 / 600e:{h(register/ref)} of every entry shown; r:{h(register)} for the list; catalog
GET /v1/find?q=&kind=&register=&locale=&limit=Type-ahead: up to 50 products (cards), categories or entries whose name in the locale holds every word typed, names that start with it first; a product by the start of each word60 / 600p:, c: or e: of everything shown; r:{h(register)} with a register; catalog
GET /v1/routes/{slug}?locale=Which product, category or entry a slug names, and its slug now; moved for a slug it held before60 / 600, a moved one 30 like a missp:, c: or e: of the target
GET /v1/products/{ref}/offers?channel=Every variant's offer of one productmin(30, next price step) / min(120, next price step), stale-while-revalidate=30op:{h(ref)}, offers
GET /v1/offers/{sku}?channel=One SKU's offersameo:{h(sku)}, op:{h(ref)}, offers
GET /v1/shopsThe shop's identity as the settings in force say: its name, its languages and each Channel's currency, gross or net prices, country, languages and storefronts, and the capabilities resources bring by label, which OrbCart, OrbPage and the shop read rather than keep (shops())60 / 600settings, purged by every settings publish
GET /v1/openapi.jsonThe contract with every published Type as a schema, and each route's problems by status and code60 / 600schema
GET /v1/media/{id}?locale=A file of the media library as a shop shows it: its url with every narrower rendition as srcset, its focalPoint and its alt in the locale (media(id, { locale }))60 / 600m:{h(id)}, catalog
GET /v1/locations?channel=The open Locations that serve a Channel, by name: address, coordinates, phone, services, the weekly hours and the next 14 days, each with when it is open as moments and why it differs (locations.list(channel))60 / 600, ending when the first of them starts its next daylocations, catalog
GET /v1/appointments/free-times?location=&sku=&from=&days=&quantity=&resource=When a product may start at a Location for up to 14 days, each start with its end and resources (appointments.freeTimes(…))10 seconds at mostoffers
GET /media/{id}/{version}An owned original at its full SHA-256 digest; current reads a mutable registered private original31536000 / 31536000, immutable; current: 30 / 30Owned images need no purge; current: m:{h(id)}
GET /media/{id}/{version}/{width}The versioned image scaled down to a rendition width as WebP; wrong versions or widths are 404 media_not_found, never replacement bytessamesame
GET /.well-known/jwks.jsonThe catalog's public keys, which verify every event it signs (webhooks)60 / 600catalog
  • Every query is a strict allowlist: an unknown parameter or a repeated scalar parameter is 400 parameter_unsupported, so every key in the cache is a key we meant. Explicitly declared bounded arrays use repeated parameter names within their declared limits. A malformed value is 400 parameter_invalid at its pointer, such as #/query/locale.
  • Every public read has one spelling: its parameters in the route table's order, a default left out, a number without leading zeros, each value percent-encoded but for RFC 3986's unreserved characters (A-Z a-z 0-9 - . _ ~). Any other spelling (?locale=de&category=angebote, limit=25, limit=010, outdoor/rucksaecke for outdoor%2Frucksaecke) is a 308 to it, decided from the URL alone before the miss budget and kept as long as base data, so a scan that varies only the spelling never reaches the database. There is no generic, unbounded ids= read. Native batch operations such as category presence explicitly bound their input arrays and query work.
  • An explicitly supplied default redirects too: days=7 on appointment free times receives a 308 to the URL without days. Omit defaults or follow redirects, for example with curl -L.
  • HEAD answers as GET does, with its status and headers and no body, so a CDN, a link checker or curl -I sees what is there. A HEAD of an image reads none of its bytes.
  • Renditions. An image is shown at 160, 320, 640, 960, 1280 or 1920 px and at no other width: every width the catalog hands out is snapped up to the next of these, and a width at or past the original is the original. Where MEDIA_TRANSFORM is cloudflare, the first request of a rendition makes it through Cloudflare's Images binding and keeps it in the bucket, so each picture at each width is paid once per byte version; bunny puts a bunny.net pull zone in front of /media/{id}/{version} and asks it for ?width=, at a flat price per website; imgproxy is an externally operated choice; none shows only the originals. Every delivered image carries its narrower renditions as srcset, so a page gives sizes and a phone loads the width its space needs. OrbCart's line image is the widest rendition at most 400 px on its longer side.
  • Registered private images. /media/{id}/current and its Cloudflare variant route serve selected registered originals after their transactional media task installs a protected locator. Image delivery reads private storage, not Postgres, and never exposes the locator or raw object key. HEAD and conditional GET use the same validators; generated variant keys encode the whole opaque original ETag. Store identity must match before raw access. Public CDN references keep their exact external URLs and are never proxied or redirected. See private storage and protected-origin recipes; CloudFront needs an explicit cache policy and does not consume Catalog's targeted CDN headers or tag purges automatically.
  • Never s-maxage (Cloudflare turns stale-while-revalidate off with it). The edge lifetime goes in the header the CDN reads, which its adapter names: Cloudflare-CDN-Cache-Control on Cloudflare (the family's rule, measured in S1), CDN-Cache-Control (RFC 9213) on Varnish and other CDNs.
  • Product pages keep base data separate from offers. Cards may include an offer by asking with channel, using the shorter offer lifetime for the whole answer. Every lifetime is clamped to the next moment the answer changes on its own: a scheduled version, a product joining or leaving a listing, a price step. A boundary inside the fresh lifetime ends it there, drops stale-while-revalidate and sends stale-if-error=0; a boundary beyond it but inside the stale windows trims them to end at the boundary. Any answer cut this way is 200, never 304, so a sale that starts at 12:00 is live at 12:00 without a purge, and nothing serves the old price past it, not even when the origin fails.
  • A product scheduled for Friday 09:00 is served, listed in its categories and found at its new slug from 09:00, with every answer before it living until 09:00. The read judges the time; nothing has to run at 09:00 for the storefront to be right.
  • Weak ETag over the body; 304 only at the default lifetime. A product that is not there is 404 product_not_found, public, max-age=30, stale-if-error=0, tagged with its p: tag, so its first publish clears it. No 410.
  • Misses are rationed. A request the cache did not answer spends from a budget per route and client network before it reads the database; over budget is 429 rate_limited, private, no-store. A scan of made-up refs, each a miss past the 30-second negative cache, cannot become a scan of Postgres.
  • Storefront reads through catalog({ url }) retry once after one second if the connection fails, the answer is 429 or 5xx, or it carries Retry-After. A persistent failure is returned as CatalogUnreachable or CatalogError; an abort is not retried. This does not change Source write retries.
  • Every product carries version, publishedAt and sequence; every offer sequence and validUntil.
  • An offer of goods sold by measure carries unitPrice, the price in force per its Type's reference unit, such as { price: { amount: 1990, currency: "EUR" }, per: "kg" } for 500 g at 9,95 €. It is worked out on every read, rounded to the minor unit half up, so it moves with a sale and needs no purge of its own. per is one of kg, 100g, l, 100ml, m, m2; goods sold by the piece have none.
  • While a sale runs, an offer carries lowestPrior, the lowest price in force in the 30 days before the sale began, for the EU's price indication rule. It is taken from the prices shoppers were shown in those days, once the sale has begun: a sale recorded ahead of time gets it at its start, so it may appear up to one offer lifetime later. A product with no price in those days has none.
  • A purge makes it fresher sooner. The lifetimes are the guarantee.
  • Owned image responses, including HEAD and 304, answer public, max-age=31536000, immutable in browser and edge headers. Delivery resolves the current media digest, so replacement produces new URLs without waiting for an image lifetime. Old or wrong digests return an uncacheable 404 after replacement. Media tags still purge documents containing these URLs, not immutable image responses. Registered /current responses retain 30-second browser/edge lifetimes with explicit zero stale windows. CloudFront must respect these distinct policies without conflicting TTL overrides. Already-painted images do not refresh themselves, and document caching policies are unchanged. See replacement freshness.

Staff GET /panel/media/{id} includes replacement: "in-place" | "owned-copy" | "none" beside the file and its uses. PUT /panel/media/{id}/owned-copy takes new image bytes with the existing content-edit authority and adopts them at a registered file's ID without mutating the original. Ordinary PUT /panel/media/{id} remains managed-only. Digest deduplication and proportions apply to both. Repeating adoption with the same bytes is unchanged; different bytes after adoption conflict with media_changed. Sources cannot authorize or perform adoption.

GET /v1/appointments/needs/{sku} returns the complete effective AppointmentNeeds for one live SKU: its variant override, otherwise its Type default. catalog.appointments.needs(sku) returns { status: "found", needs }, appointments_off or appointments_not_taken. Its offer-class lifetime is 30 seconds in the browser / 120 at the edge, clamped to the next scheduled version, with settings, catalog and the product's p: tags; it is not permission to book. Staff product handover is the uncached POST /panel/products/{ref}/handover management route, described in Sync from a PIM or ERP, as are the Type change's POST /panel/products/{ref}/type/preview and POST /panel/products/{ref}/type and an editor's withdrawal, POST /panel/products/{ref}/publication with { state: "withdrawn" | "live" }.

Category navigation tree

GET /v1/category-tree?parent=&depth=&locale= returns { object: "list", data: DeliveredCategory[] }, with no pagination or truncation. The client's categoryTree({ locale, depth: 2 }) reads a whole menu in one request; categories({ parent, locale }) remains the paged one-level read.

depth is a positive integer, defaulting to two. Roots count as level one; with parent, its children count as level one and the parent itself is excluded. Categories are depth first, parents before children, siblings by position then creation order. Every row retains its full path and locale-aware hasChildren, including at the cutoff. Unpublished categories and branches whose ancestor did not release the locale are omitted. A parent that is not live returns 404 category_not_found; a live parent unavailable in the locale returns an empty list. An unsupported locale returns locale_unsupported. Omitting locale uses the catalog default.

The answer uses the base lifetime (60 seconds in browsers, 600 at the edge), a weak ETag and conditional 304. It carries every shown category's and ancestor's c: tag, roots when reading roots, and catalog, so publishing, renaming, moving or withdrawing a branch invalidates the menu as well as one-level reads.

Category product presence

Use one native client read to decide which navigation categories contain live products of selected Types, including every visible descendant. No product pages, counts, prices or stock are read:

import { catalog } from "@orbcatalog/client";

export async function sellingCategories(url: string) {
  const shop = catalog({ url });
  const presence = await shop.categoryPresence({
    categories: ["outdoor", "angebote"],
    types: ["backpack", "jacket"],
    locale: "de",
    channel: "de",
  });
  return new Set(presence.data.filter((row) => row.hasProducts).map((row) => row.ref));
}

GET /v1/category-presence?category=outdoor&category=angebote&type=backpack&type=jacket&locale=de&channel=de returns { object: "list", data: [{ ref, hasProducts }], validUntil? }. Category refs are deduplicated and sorted; Type keys are combined with OR. Unknown Types match nothing. Unknown, unpublished or locale-hidden categories answer false, as do their descendants when any ancestor is hidden. Products must be live, listed now and released in the requested locale; discontinued and withdrawn products never qualify. The Channel must exist and support the locale. It selects the storefront language, not an offer-availability condition: a live product needs no price or stock to qualify.

A request accepts 1–64 category refs and 1–32 Type keys. It traverses at most 64 ancestor levels and 1024 category memberships across the requested subtrees (overlapping subtrees count separately), with at most 800 distinct categories including ancestors and unknown requested refs so cache tags stay below Cloudflare's 16 KB header limit. Larger subtrees return parameter_invalid, never truncated answers; split the batch or select narrower categories. Existence checks use indexed listings and product rows and stop at a match, regardless of how many other Types precede it in a listing.

The base cache lifetime is 60 seconds in browsers / 600 at the edge. Every requested, descendant and ancestor category is tagged, including empty and unknown requested categories; normal product-publication, withdrawal and category-change purges invalidate affected answers. schema and settings tags cover Type-key and Channel changes. For a bounded indexed boundary read, the lifetime is conservatively clamped to the next scheduled product publication anywhere in the catalog, even outside the selected subtrees. The read evaluates scheduled versions at their time without waiting for settlement. validUntil exposes that same boundary to callers maintaining their own caches: never retain an answer or serve it stale beyond it. Purges accelerate freshness; the bounded lifetime is the guarantee. Independent application caches must consume invalidations or retain their own bounded freshness policy rather than assuming CDN purges evict application memory.

Category subtree listings

By default, products lists only products linked directly to the selected category. Pass descendants: true to include its live descendants at every depth:

src/category-products.ts
import { catalog } from "@orbcatalog/client";

export async function categoryProducts(url: string, after?: string) {
  const shop = catalog({ url });
  return shop.products({
    category: "outdoor",
    descendants: true,
    locale: "de",
    channel: "de",
    limit: 20,
    after,
  });
}

The HTTP parameter is descendants=true; omitted or false keeps direct membership. Each product appears once, even when linked to the parent and a child or to several descendants. The selected category's pinned products lead in their pinned order; pins in descendants apply only to those categories' own listings. The rest follows first-publication time, newest first, with a stable product tie-breaker. One next cursor pages the entire result: pass it back as after, keeping the category and descendants unchanged.

Subtree answers carry every included category's cache tag, including empty descendants, so a product joining any of them purges the answer. Scheduled membership changes anywhere in the subtree clamp its lifetime. The usual locale and Channel rules, card slug and optional offer are unchanged.

Product cards with prices

Every product card carries its localized slug; no URL parsing is needed. Pass channel to products or product find to include the card's offer in the same request:

src/product-cards.ts
import { catalog } from "@orbcatalog/client";

export async function productCards(url: string) {
  const shop = catalog({ url });
  return shop.products({ category: "outdoor/rucksaecke", locale: "de", channel: "de" });
}

The equivalent routes are GET /v1/products?category=outdoor%2Frucksaecke&locale=de&channel=de and GET /v1/find?q=Alpin&kind=product&locale=de&channel=de.

offer is the normal delivered offer, including its SKU, Channel, price, compareAt, sale window, unit price and availability. It belongs to the cheapest orderable variant of the published version; limited, preorder and backorder are orderable. If every priced variant is out of stock, it shows the cheapest one with out_of_stock. Equal prices keep published variant order. No price in force, a discontinued product or no channel means no offer. A Channel outside the current settings returns channel_unsupported.

These reads batch the page's offers internally; they spend only the listing or find miss budget, not one offer miss per card. With a Channel, the product-card answer uses the offer lifetime (30 seconds in the browser, 120 at the edge, or 10 seconds when it shows a limited offer), carries offers and each product's op: tag, and end at the next price step of any variant, including one whose future sale could become cheapest. Existing product and listing boundaries still apply. The card is a browsing hint: the offer read and OrbCart's quote remain authoritative at checkout. OrbPage's content cards are unchanged and carry no prices.

The management client

The panel's routes under /panel are the staff side of the same contract: what an editor's panel reads and writes with a staff token. @orbcatalog/client/staff calls them the way the panel does, and the panel calls no catalog route by hand, so a change to a route breaks the panel and every other caller at compile time. Each call is parsed with the route's own schema, and a refusal is a value, never a throw.

src/skis.ts
import { staffCatalog } from "@orbcatalog/client/staff";

export async function jacketsToCheck(staffToken: string) {
  const catalog = staffCatalog({
    url: "https://catalog.example.com",
    fetch: (request) => {
      request.headers.set("Authorization", `Bearer ${staffToken}`);
      return fetch(request);
    },
  });

  const page = await catalog.grid({ search: "ski jacket", limit: 25 });
  if (!page.ok) throw new Error(page.problem.detail);
  return page.value.rows.map(({ ref, revision }) => ({ ref, revision }));
}

fetch is yours: it sends the staff token, and the admin's panel renews it once on a 401. catalog.product(ref) reads a product with its draft, live version and owned fields, catalog.history(ref) its versions. A call answers { ok: true, value } or { ok: false, problem }. A catalog that does not answer, or answers something the client cannot read, is a problem of the client's own (unreachable, unreadable) with status 0. A write takes an Idempotency-Key, so a retry lands once. Agents read through the MCP endpoint, which runs the same reads.

On this page