Skip to Content
Run it

ORBCOMMERCE DOCUMENTATION

Connect the products

Point OrbPage, OrbCart and OrbSearch at the catalog, with the variables, secrets and calls each needs.

OrbPage reads products, categories and listings through @orbcatalog/client, as a storefront does. Point it at the catalog and the Channel its site belongs to:

# OrbPage's wrangler.jsonc vars
CATALOG_URL=https://catalog.nordgrat.de
CATALOG_CHANNEL=de   # its cards link into this Channel's shop, so an Austrian site's lead to nordgrat.at

A card shows a product's name, its address in that Channel's shop and its first picture; a discontinued product, one the catalog does not deliver and one not released in the page's language are left out and named in OrbPage's meta.unresolved. No price and no availability, because OrbPage keeps a page for a minute and hears of no change, so a card could show a price checkout no longer charges.

OrbCart borrows offers through its signed HTTP transport. No code in the merchant's Worker: its http() posts to exactly the address it is given and signs every call with the environment's key.

// OrbCart's src/worker.ts
import { defineCommerce, http } from "@orbcart/runtime";

export default defineCommerce({
  channels,
  offers: http("https://catalog.nordgrat.de/orbcart/offers"),
  inventory: {
    check: http("https://catalog.nordgrat.de/orbcart/inventory/check"),
    reserve: http("https://catalog.nordgrat.de/orbcart/inventory/reserve"),
    release: http("https://catalog.nordgrat.de/orbcart/inventory/release"),
    commit: http("https://catalog.nordgrat.de/orbcart/inventory/commit"),
    restock: http("https://catalog.nordgrat.de/orbcart/inventory/restock"),
  },
});

The catalog trusts that one environment: its keys at ORBCART_URL/.well-known/jwks.json verify every call, and its secret key sends the invalidations.

# wrangler.jsonc vars: "ORBCART_URL": "https://commerce.nordgrat.de"
npx wrangler secret put ORBCART_SECRET_KEY   # its sk_live_…; .dev.vars locally

When OrbCart's Worker runs in the catalog's Cloudflare account, bind it to the catalog instead: no public gateway, no signature and no fetch of OrbCart's keys stands between them. Export the entrypoint from the catalog's Worker beside its default export, export const OrbCart = orbCartEntrypoint(nordgrat) from @orbcatalog/runtime/cloudflare, bind OrbCart's Worker to it:

// OrbCart's wrangler.jsonc
"services": [{ "binding": "CATALOG", "service": "orbcatalog", "entrypoint": "OrbCart" }]

and attach the contracts to the binding. OrbCart calls each at its own path, such as /offers or /pickup-locations, and the entrypoint answers it with the /orbcart route there; appointments attach the same way.

// OrbCart's src/worker.ts
import { defineCommerce, service } from "@orbcart/runtime";

export default defineCommerce({
  channels,
  offers: service("CATALOG"),
  pickupLocations: service("CATALOG"),
  inventory: {
    check: service("CATALOG"),
    reserve: service("CATALOG"),
    release: service("CATALOG"),
    commit: service("CATALOG"),
    restock: service("CATALOG"),
  },
});

Only a Worker of the same account that is bound to the entrypoint reaches it, so the binding is the authentication. A call still names its context.environment, and each route still refuses a Channel the catalog does not sell in. The public /orbcart routes keep verifying every signature, for an OrbCart in another account or any other caller, and the invalidations still go out with ORBCART_URL and ORBCART_SECRET_KEY.

POST /orbcart/offers verifies the RFC 9421 signature (tag="orbcart-contract", an Idempotency-Key covered wherever a call sends one), reads the SKU's Variant and its Offer for context.channel from the database primary (never the CDN, for display and quote alike) as they stand when the answer reaches OrbCart, at most three seconds on, so a price step on the way never arrives expired, and answers each reference with title ("Alpin 30", in the first of the Channel's languages the version is released in) with the Variant's options as attributes ({ "Farbe": "Grün" }), price in minor units, compareAt, taxCategory, shipping with its weightInGrams, image at most 400 px on its longer side, limits (a minimum above the maximum or above the 9,999 units a line holds is refused where it is written), deliveryTime wherever the Offer states its delivery days ("5–9 Tage"), expiresAt at the next price step or scheduled version and at most 15 minutes ahead, and tags: ["p:BP-ALPIN-30"]. A cart in another currency than its Channel is refused. A reference the catalog cannot sell is unavailable, and says why: unknown, unavailable, discontinued, not_offered or out_of_stock. When a SKU's price or availability moves, or a product is published, discontinued or withdrawn, the catalog calls OrbCart's POST /v1/offers/invalidate with the SKUs and tags, so open carts borrow again at once instead of at expiresAt; until OrbCart takes it, only that call waits.

inventory is the one place OrbCart is told about stock, whether an editor or a Source counts. The four routes verify the same signature and read and write the primary. check answers each counted SKU's available, the count less the orders booked since it and the holds open now; a SKU without a count is left out, which OrbCart reads as unlimited. reserve holds, under a lock on the SKUs' counts taken in SKU order, what is available of each up to what the hold asks, and answers what fell short as [{ reference, reserved }]; the same hold again holds nothing twice, a later expiresAt extends it, and what an open hold holds stays held, since OrbCart extends a hold with its quote's quantities and reads no answer. release frees a hold, a second time too. commit books the hold for the order and answers what it could not book as [{ reference, committed }], never more than held; a hold that ran out or was released meanwhile, or whose count fell, books what is still available. A hold OrbCart never releases stops counting at its expiresAt. OrbCart's Idempotency-Key is the hold's id on all three: the catalog keys the hold's units and its bookings by it, so each call is idempotent on its own, and a repeat with a new request id changes nothing.

OrbSearch takes what it accepts today. Point it at the feed, polled every 10, 30, 60, 180, 360, 720 or 1440 minutes:

Published products whose Type takes appointments are discoverable without an offer in each Channel that sells a released locale, while appointments are enabled. The feed sends those Channels as entity membership and keeps the actual variants and offers; it invents no price, stock or availability. Other products need a real offer for Channel visibility. OrbSearch still applies its Channel assortments and permissions, and real offers independently confer visibility. Withdrawn and discontinued products leave the next feed; reindex after adopting this feed and an OrbSearch engine that supports entity membership. Keep the Channels configured in OrbSearch's release in step with the catalog.

curl -X PUT https://search.nordgrat.de/api/v1/catalog-source \
  -H "Authorization: Bearer $ORBSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://catalog.nordgrat.de/feeds/orbsearch.ndjson","interval_minutes":10}'

and give the catalog OrbSearch's control plane and management key, so it pushes offers:

# wrangler.jsonc vars: "ORBSEARCH_URL": "https://search.nordgrat.de"
npx wrangler secret put ORBSEARCH_KEY   # .dev.vars locally

For Workers in the same account, add an HTTP service binding on the Catalog Worker instead of sending offer updates through a public gateway:

"services": [{ "binding": "ORBSEARCH", "service": "orbsearch-gateway" }]

Keep ORBSEARCH_URL and ORBSEARCH_KEY: the URL still supplies the request's address and the management key still authenticates it. The optional ORBSEARCH binding carries only Search offer updates, including retries and scheduled sale resends. Source media, Cart and webhooks keep their own transport. Without the binding, external deployments continue using HTTP. Outside Workers, an optional orbSearch.fetch transport can be supplied alongside its URL and key in the runtime ports.

Each variant carries its own colour's main image (or a shared image, never another colour's), its product URL and its actual offers only in Channels with a released locale. Search returns the SKU alongside the URL; a storefront can add its own variant-selection parameter. Catalog does not invent a variant URL convention.

Products and variants also carry media: at most one primary card-width image with its actual URL, dimensions, available srcset and alt text in the released locales. A variant's own colour image takes precedence over a shared image. An explicit media: [] means that no image matches; Search must not fall back to another colour's product image. Omitting media remains the legacy image/images behavior for other feed producers. Linked external renditions stay direct CDN URLs and are never invented or rewritten. Full product galleries remain available through Catalog's product delivery, not this listing feed.

Every delivered SKU carries explicit purchase requirements: its published quantity minimum (one when absent), whole-unit increment of one and optional maximum, plus requires_configuration. Appointment needs follow the same rule as the public appointment read: a variant's complete override, otherwise its Type's default. Any published appointment requirement prevents direct quick-add, including while appointment booking is switched off. Draft edits never change these facts; a scheduled publication changes them at its delivery boundary. Requirements belong to each SKU, not a guessed family default. They authorize no purchase: Search must consider every eligible SKU before limiting previews, and Cart still validates quantities, stock and configuration.

Feed offers and incremental pushes share the same commercial projection: explicit currency, base and sale price, their comparison prices and unit prices, refundable deposit, availability including limited, and delivery days. Amounts are in the currency's major unit. Unit prices use the published net content and Type reference unit, with the same rounding as public offers and Cart; the deposit remains separate. Search switches price/unit_price to sale_price/sale_unit_price together inside the same sale_window, then restores both base values when it ends. Queued sales are pushed again at their scheduled transitions.

Incremental changes leave omitted fields unchanged, clear fields with null, and replace fields with values. Catalog explicitly clears removed deposits, unit prices and delivery days. end_sale clears the sale's price, window, comparison and unit price; remove: true removes an offer without a base price. Exact stock counts are not projected: public stock bands are display facts, and Cart checks and reserves stock authoritatively.

Content freshness follows feed imports, not offer pushes: publication, withdrawal, changed pictures and changed measurements move the feed's ETag. A draft does not. Configure and monitor the import interval separately from offer propagation; a fast price push is not proof of fast content updates. Cart and checkout remain authoritative for all purchase decisions.

The feed is the category tree, then every product that sells now, one OrbSearch entity per line. It opens with every delivered category, parents before their children, as an OrbSearch category: its title, URL and path in each locale it and its ancestors released, its parent, and its description as plain words, so a category page in search lists the products of the categories below it. Then the products, read a page at a time while it is sent: each product's name and URL in each released locale (OrbSearch keeps one URL per locale, so a locale's is its address in the first Channel that sells it), its description as plain words, its first image, brand, categories and list attributes, and its variants by their axes with their offers per Channel in OrbSearch's own shape (major units, its availability enum). A discontinued product leaves search. The attribute with the brand role is the entity's brand, the one with the description role (a text or rich text, per product) its description, and an attribute under a word OrbSearch keeps for a field of its own (price, availability, category, rating and the rest its contract lists) is not sent: OrbSearch fills those fields from the offers, the categories and its ranking signals. Its ETag moves only when published base data does (a product, a category, the Schema, the Channels or languages of the settings) or the catalog writes it otherwise (a deploy, a change of the Worker's settings, another media service), and no cache keeps the feed (private, no-store), since a kept copy would bring back a price pushed since, so every poll reaches the ETag: an unchanged catalog, or one whose prices alone moved, costs OrbSearch a 304. Offer changes are pushed to PUT /api/v1/offers in batches of 1,000 as they happen, a sale with its sale_window so OrbSearch ends it by its own clock: a price is live in search in seconds, not at the next poll. An offer of a product OrbSearch has not imported yet is left to the feed, which brings the product with its offers.