Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

Read the catalog

Product, category and brand pages, a store finder, free times and the mini cart, with @orbcatalog/client.

npm i @orbcatalog/client
npx orbcatalog types --url https://catalog.nordgrat.de > app/catalog.types.ts   # from the live OpenAPI
npx orbcatalog types --url https://catalog.nordgrat.de --check app/catalog.types.ts   # in CI: fails after a Schema publish

The file holds one shape per Type and names the Schema it came from. It is the same byte for byte for the same Schema, so keep your formatter off it.

Product page

import { catalog } from "@orbcatalog/client";
import type { Nordgrat } from "~/catalog.types";

const nordgrat = catalog<Nordgrat>({ url: "https://catalog.nordgrat.de" });

export async function loader({ params }: LoaderArgs) {
  const route = await nordgrat.route(params.slug, { locale: "de" }); // slug -> ref, cached
  if (route.status === "not_found" || route.kind !== "product") throw notFound();

  const [found, offers] = await Promise.all([
    nordgrat.product(route.ref, { locale: "de" }), // base data, cached long
    nordgrat.offers(route.ref, { channel: "de" }), // every variant's offer, cached seconds
  ]);
  if (found.status !== "found") throw notFound();

  const { product } = found;
  if (route.status === "moved" && product.urls.de !== undefined)
    throw redirect(product.urls.de, 301);
  if (product.type === "backpack") {
    const [brand] = product.attributes.brand; // { ref: "deuter", name: "Deuter", slug: "deuter", image }: the logo without a second call
    product.attributes.volume; // { value: 30, unit: "l" }, typed from the Schema; optional while a live backpack may lack it
  }
  product.labels.brand; // "Marke": each attribute's label in the product's locale, from the Schema
  product.urls; // { de: "https://nordgrat.de/p/alpin-30", ch: "https://nordgrat.ch/de/p/alpin-30" }
  product.alternates; // { de: { de: …, ch: … }, en: { de: "https://nordgrat.com/p/alpine-30" }, fr: { ch: … } }
  product.search; // { title: "Alpin 30 Wanderrucksack", description?: … }: the title is the name until one is written
  return { product, offers: offers.data, canonical: product.urls.de };
}

An offer of goods sold by measure carries its unit price beside its price: show it wherever the price stands, in the shopper's currency, such as "19,90 € / 1 kg". The catalog works it out from the price in force, so during a sale it is the sale's.

const per = { kg: "1 kg", "100g": "100 g", l: "1 l", "100ml": "100 ml", m: "1 m", m2: "1 m²" };
const coffee = await nordgrat.offer("HK-BERGKAFFEE-500", { channel: "de" });
if (coffee.status === "found" && coffee.offer.unitPrice) {
  const { price, per: unit } = coffee.offer.unitPrice; // { price: { amount: 1990, currency: "EUR" }, per: "kg" }
  const euros = new Intl.NumberFormat("de-DE", { style: "currency", currency: price.currency });
  console.log(`${euros.format(price.amount / 100)} / ${per[unit]}`); // "19,90 € / 1 kg"
}

Every Channel that sells a locale shares its text, and each keeps its own address: urls holds one per Channel, from that Channel's storefront in the catalog's settings. A German shop and an Austrian one read the same answer, link to their own origins and name each other as hreflang alternates, and alternates holds those urls for every locale the product is released in, so one answer writes every <link rel="alternate">. search is what a result page shows: the title the editors wrote for it, else the name, and a description only where one is written, since a search engine picks its own snippet otherwise.

A slug the product held before answers moved with the slug it has now, so the page answers 301 rather than 404, through any chain of renames, until another product, category or entry takes the old slug; a product that is no longer live is a 404 at every slug it held.

Storefront paths

Each Channel's storefront sets paths independently per locale. product is the default; productByType overrides it by the published Type's key, never by a category, SKU or product name:

{
  "origin": "https://nordgrat.de",
  "product": "/p/{slug}",
  "productByType": { "backpack": "/rucksaecke/{slug}", "service": "/service/{slug}" },
  "category": "/shop/{path}",
  "entry": "/{register}/{slug}"
}

With category: "/shop/{path}", a category at outdoor → rucksaecke lives at /shop/outdoor/rucksaecke. Every segment comes from that ancestor's published slug in the requested locale, not its ref. {slug} deliberately keeps a leaf-only category path. Slugs remain single segments; URL encoding is applied per segment. Paths contain one {slug} (products and entries), or one {slug} or {path} (categories), without a query or fragment. The panel's Shops settings edits these paths and offers a path for each published Type.

Product pages, cards, cart lines, search feeds, category breadcrumbs and language alternates use these same settings. A parent rename or move changes descendant addresses on their next read and purges cached answers through their ancestor tags. A locale missing anywhere in the ancestor line is not delivered. Settings changes invalidate delivery and the search feed. No redirect history is created for template changes or ancestor moves: the storefront owns legacy-path handling and should use delivered urls, not reconstruct paths from a leaf slug. route() still resolves a single slug, not a full storefront path.

Sitemap addresses

for await (const entry of nordgrat.sitemap({ channel: "de", locale: "de" })) {
  entry.url; // the canonical address in this Channel and locale
  entry.alternates; // { de: "https://nordgrat.de/…", en: "https://nordgrat.com/…" }
}

The public /feeds/sitemap.ndjson?channel=de&locale=de stream reads published products and categories in bounded pages from the primary, using the same URL derivation as delivery and search. It includes readable discontinued product pages, excludes drafts, withdrawn products and unreleased category branches, and needs no offer. Only languages sold by the selected Channel appear in its alternates. No cache keeps this stream; restarting a failed generation starts a fresh walk. The client cancels the body when iteration stops early. Write these entries into your storefront's XML sitemaps, partitioning at the sitemap protocol's size and URL limits. Add content pages and register entries through their own public reads; the catalog stream covers products and categories, not the whole site.

What is not there is an answer to switch on: not_found, locale_unavailable, and no offers for a product that is not live. A request the catalog calls invalid (a locale it does not write, an unknown parameter) or could not answer (429, 5xx) throws CatalogError with the problem and its requestId, and an answer that is not the catalog's (a proxy's error page, a storefront's own) throws it without one; a network that failed throws what fetch threw. The client writes every query in one spelling, the contract's order with defaults left out, so one question is one cache key.

Shipping restrictions and limits

Each variant carries what its published version says about shipping and how many a buyer may order in one Line, so a checkout that also sells goods of its own can refuse a method a variant cannot go by:

const alpine = await nordgrat.product("BP-ALPIN-30", { locale: "de" });
if (alpine.status === "found") {
  for (const variant of alpine.product.variants) {
    variant.shipping; // { weightInGrams: 18000, restrictions: ["bulky", "pickup_only"] }: traits a shipping rule can exclude
    variant.limits; // { max: 2 }: units per Line; absent when any quantity sells
  }
}

They change with the next publish, like the rest of the product. They are a description, not a sale: what a variant costs, until when and with which tags is the catalog's offer, which OrbCart takes signed. A product page shows these facts; it never builds an offer from them.

Category page without OrbSearch

A navigation menu reads every category down to its chosen depth in one cached request:

const menu = await nordgrat.categoryTree({ locale: "de", depth: 2 });
// menu.data: all roots and their children, depth first; no next cursor or per-parent reads
const branch = await nordgrat.categoryTree({ parent: "outdoor", locale: "de", depth: 3 });
// branch.data: three levels below outdoor, excluding outdoor itself

Depth is a positive integer and defaults to two. Roots (or children of parent) are level one. Siblings keep position order, with equal positions keeping creation order. Each category carries its parent, full breadcrumb path, URLs and hasChildren, which stays true at the depth cutoff if more children are visible. Only published categories whose entire ancestor line released the locale appear; a hidden branch is never promoted to the roots. An unknown or unpublished parent gives the client an empty list. The existing categories call still returns a paged, single level.

const category = await nordgrat.category("outdoor/rucksaecke", { locale: "de" });
if (category.status !== "found") throw notFound();
category.category.path; // [{ ref: "outdoor", title: "Outdoor", slug: "outdoor", urls: { de: "https://nordgrat.de/c/outdoor" } }]: the breadcrumb
category.category.alternates; // { de: { de: …/c/rucksaecke }, en: { de: "https://nordgrat.com/c/backpacks" } }
category.category.search; // { title: "Wanderrucksäcke", description?: … }: its title until one is written
const children = await nordgrat.categories({ parent: "outdoor/rucksaecke", locale: "de" });
const page = await nordgrat.products({
  category: "outdoor/rucksaecke",
  locale: "de",
  limit: 24,
  after: new URL(request.url).searchParams.get("after") ?? undefined,
});
// page.data: ProductCard[] (name, urls by Channel, image with width and height, the Type's list attributes)
// page.next: the cursor of the next page, absent on the last

Brand page

const route = await nordgrat.route("deuter", { locale: "de" }); // { kind: "entry", register: "brands", ref: "deuter" }
if (route.status !== "found" || route.kind !== "entry") throw notFound();
const found = await nordgrat.entry(route.register, route.ref, { locale: "de" });
if (found.status !== "found") throw notFound();
found.entry.description?.html; // the brand's text; `image` its logo, `link` its own site
found.entry.alternates; // its `urls` in every locale it is released in, as a product's and a category's; `search` its search listing
const brands = await nordgrat.entries("brands", { locale: "de", limit: 100 }); // every live brand, by name

A storefront's entry template (/{register}/{slug} unless the Channel names another) gives the entry's urls. A brand's products are OrbSearch's facet, since brand is its field already.

Store finder

const stores = await nordgrat.locations.list("de"); // every open Location that serves the Channel, by name
for (const store of stores) {
  store.address; // { line1: "Sendlinger Straße 12", postalCode: "80331", city: "München", country: "DE" }; absent at a warehouse nobody visits
  store.services; // ["pickup"]: what it does, beside "shipping" and "appointments"
  store.hours; // the weekly rule and its exceptions, as `openingHoursSpecification` writes them
  store.days[0]; // { date: "2026-10-01", open: [{ start, end }] }: today on its own clock; a closed day has none and its `reason`
}

A Location is a record of its own, edited in place in the panel's Settings and live at once; the list is purged when one changes and holds until the first of them starts its next day. Its coordinates and phone are what a map service matches a store by.

Every new catalog starts with a shipping Location named Warehouse, ID loc_warehouse000. It initially serves no Channels, so it does not appear in a Channel's public Location list until assigned to one.

Free times for an appointment

const times = await nordgrat.appointments.freeTimes({
  location: "loc_muenchen0001",
  sku: "SV-SKI-SERVICE",
  from: "2026-12-05T00:00:00+01:00",
  days: 7, // at most 14
});
times[0]; // { start, end, resources: ["res_…", "res_…"] }: each start on the Location's grid, with the resources it would take

A product takes appointments when its variant or Type default says what it needs (capabilities at once, a duration fixed or per unit, buffers, a lead time of its own) and the Location takes appointments, while the owner has switched them on in the settings; otherwise the list is empty. A variant's complete appointments replaces the Type default, never merges with it: omitted optional lead time or resource choice does not inherit from the Type. Without an override, the Type default applies unchanged. Free times and appointment writes use the same effective needs, while front-desk policies still apply.

const effective = await nordgrat.appointments.needs("SV-SKI-SERVICE");
if (effective.status === "found") {
  effective.needs.requirements; // capabilities grouped per concrete resource
  if (effective.needs.mode === "work") effective.needs.duration;
  effective.needs.buffer;
  effective.needs.leadMinutes; // absent does not inherit a Type value
  effective.needs.choice;
}
// Otherwise: appointments_off or appointments_not_taken (unknown/non-live SKU or no needs).

GET /v1/appointments/needs/{sku} reads only effective published needs, not draft overrides. A per-appointment work job takes its duration once, even with quantity four; only per: "unit" multiplies by the appointment line quantity, never a merchant's configuration metadata. Rentals use an explicit return end instead. Free times are computed and private/no-store: a reservation decides, and the database never lets two appointments take one resource's time. A resource the shopper names counts only for the capability the effective needs let them choose, such as a technician by name. Capabilities are kept in Settings with labels; catalog.shops() lists them.

The front desk books in the panel's Appointments area: a contact (a name, a phone and an email if they have them) and a note go with a booking, are saved again later and are read only by staff with the area, never in an event. The staff may book or move an appointment to any resource of the Location that brings a capability the job needs, and read the free times per resource for that (GET /panel/appointments/free-times). A resource is a person, in a colour from a fixed palette that tells them apart in the calendar, or a place, such as a workbench or a lift; free times and booking weigh both alike. Each service a Location books names the resources there that can take part in it, those that bring a capability its Type needs (GET /panel/appointments/services).

Mini cart refresh

const offer = await nordgrat.offer("BP-ALPIN-30-GRN", { channel: "ch" });
if (offer.status === "found") show(offer.offer.price); // { amount: 13900, currency: "CHF" }, a hint: OrbCart's quote decides

On this page