ORBCOMMERCE DOCUMENTATION
Sync from a PIM or ERP
A Source sends products, categories, register entries, offers and stock; each row is judged on its own.
A Source is a system that owns some fields in the products it brings. Its key authenticates it and names it; in those products the fields it owns are read-only in the panel.
import { source } from "@orbcatalog/client/source";
const akeneo = source({ url: "https://catalog.nordgrat.de", key: env.ORBCATALOG_AKENEO_KEY });
// 1. Media first, answered at once: each image is fetched in the background, once per URL and ETag.
const sent = await akeneo.media([{ url: "https://pim.nordgrat.de/assets/alpin-30-green.jpg" }]);
// rows[i]: { url, outcome: "accepted" } | { url, outcome: "rejected", errors }
const acceptedUrls = sent.rows.filter((row) => row.outcome === "accepted").map(({ url }) => url);
const rejected = await akeneo.fetchedImages(acceptedUrls); // only this batch: [{ url, outcome: "rejected", code, detail }]
// 2. Products by the merchant's id, attributes by key. NDJSON on the wire, 1,000 rows per call:
// the client splits a longer list and joins the answers, each row's pointer into the whole list.
const { rows } = await akeneo.products([
{
ref: "BP-ALPIN-30",
type: "backpack",
name: { de: "Alpin 30", en: "Alpine 30" },
attributes: { brand: "deuter", volume: 30, description: { de: "<p>Leicht und robust.</p>" } },
variants: [
{
sku: "BP-ALPIN-30-GRN",
axes: { colour: "green" },
attributes: { gtin: "4012345678901" },
weightInGrams: 1150,
},
// Goods sold by measure send their net content; their Type says what the unit price is per.
// { sku: "HK-BERGKAFFEE-500", axes: {}, netContent: { amount: 500, unit: "g" } },
],
categories: ["outdoor/rucksaecke"],
media: [
{ url: "https://pim.nordgrat.de/assets/alpin-30-green.jpg", alt: { de: "Rucksack in Grün" } },
],
},
]);
for (const row of rows) {
if (row.outcome === "rejected") report(row.ref, row.errors); // per row, like OrbSearch; the rest went through
}
// row.outcome: "created" | "updated" | "unchanged" | "rejected"- Rich text as HTML. A rich text attribute takes the HTML a PIM exports: paragraphs, lists, line breaks, bold, italic,
http(s)links and, where the attribute allows them, headings. Other elements give their text, every other attribute is dropped, and markup a parser would have to guess at is refused at its place in the row. A list item holds one paragraph and its nested lists, so the paragraphs and headings inside an<li>join with a line break, and HTML without any text is refused: leave the attribute out to send none. - Queue health. A claim counts an attempt before fetching, so even an interrupted run leaves a growing backoff and lets later tasks proceed. Image work, including waiting for one of the isolate's three image slots, stops within ten seconds or the run's remaining budget, with time reserved to record the outcome. Slots expire at that cutoff even if a request was terminated before cleanup. The dashboard's existing Delivery card shows queued and due tasks, the oldest due task (or the next retry), its attempt count and outcome; focus its outcome for the failure reason. Structured
task_queueandtask_outcomelog events carry the same task ids, types and outcomes, never image URLs. - Diff by hash. A row whose canonical hash matches the last one this Source sent is
unchangedand touches nothing: a full nightly sync of a whole catalog writes only the products that moved. - Images by URL, in the background. JPEG, PNG, WebP or AVIF up to 20 MB, over
httpsfrom a public address; never SVG, which can carry script. The media call checks each URL and answers at once, so a PIM never waits on its slowest image host; the dispatcher fetches each image in a task of its own. A host out of reach, or one answering5xxor429, is asked again with backoff, eight attempts before the image is rejected as unreachable.GET /sync/v1/media(images()) reads each image's outcome,pending,fetchedwith its id and size, orrejectedwith why, by outcome and a page at a time. Its optional repeatedurlsparameter selects up to 50 URLs belonging to this Source.fetchedImages(urls)polls only the accepted URLs you pass, in batches of 50, returning only their rejections; unrelated pending images never delay it. An empty list resolves at once; a URL not accepted from this Source throws instead of waiting forever. The size is read from the image's header, turned as a browser shows it, so a page reserves exactly its space. A URL sent before is asked again with its ETag: a304, or the same bytes, keep its id and write nothing. Changed bytes at a URL are a new file with a new id; the next product sync shows it, and older versions keep the old one. Only an editor replaces a file in place, in the media library. A row names an image by its URL or by its id; a URL never sent is refused at its pointer. A product or category naming an image not fetched yet lands without it and lands again once it arrives, as a new version when its Source publishes on sync; one whose image was rejected lands without it. - Pictures per colour. Where a Type's pictures follow one of its axes (
picturesBy, Pictures per Colour in the type designer), an image names the options it shows,{ url, shows: ["green"] }, and one that names none shows on every variant. Each green variant is delivered Green's pictures, then those of every variant, so a new green size has them with no edit and OrbCart's line shows Green's first; an option the axis does not offer is refused at its pointer. - Connected in the panel. The owner adds a Source under Connections: its name, whether it publishes on sync, and what it owns. Its key is shown once, with a copy action, and only the key's SHA-256 is stored. New key stops the old key at once; Remove ends the Source, its fields become the editors', and the prices it sent stay. Read keys are added and removed beside it. Only the owner connects: an editor's call is refused with
owner_only. - Ownership per product. Two supplier feeds may both own name, slug, variants, media, categories and the same attributes. Connecting either reserves no product fields across the catalog: each owns them only on products it successfully syncs. If both send the same product ref with overlapping ownership, the later row is rejected with
field_ownedat itsref, naming the existing owner and the conflicting fields; other rows still land. Send separate products under distinct refs. Sources with disjoint fields can contribute to the same product, and changing a Source's settings cannot claim a field another contributor already owns there. The panel and editor writes use those same per-product owners. The category tree, each register and stock remain exclusively owned catalog-wide. - Editorial products. A product an editor made, in the panel or by an import, is the editors' in every field, its brand and variants too. A Source row for it is rejected for that product alone with
product_editorialat the row'sref: leave it out of the sync, or send yours under another ref. An editor's draft of other fields is never overwritten and never published by a sync. - Per-product handover. Products-edit staff may explicitly hand one Source product to editors in the native panel or through the staff client below. Subsequent unchanged or changed Source product rows and lifecycle calls reject with
product_editorial; queued image work cannot reclaim it. Leave that ref out of future product syncs. Offers and stock remain independent, and the Source's global claims and other products are unaffected. An old completed call retried with its original idempotency key may return its historical answer; it never reapplies the write. - Variant appointment needs. A variant may send
appointmentswith completecapabilities,duration: { minutes, per: "appointment" | "unit" },buffer: { before, after }, optionalleadMinutesand optionalchoice. This replaces the Type default completely. Sending a variant list without an override on a variant removes its previous override; leaving the wholevariantsfield out changes nothing. This requires ownership of variants. Unknown capabilities cannot publish. - Publish on sync (the Source's setting): the sync publishes the Source's own fields at once, as a scoped publish that leaves an editor's unfinished draft untouched. With review, the change waits in the draft.
- One owner of the tree. The Source that owns the category tree sends every category's document and its place, a parent before its children, as HTML where it describes one. Any other Source is refused with
tree_not_owned. A parent the catalog does not know, or one that would close a cycle, is refused at the row's pointer; moving a node moves its subtree, and is live at once.
await akeneo.categories([
{ ref: "outdoor", position: 0, title: { de: "Outdoor" }, slug: { de: "outdoor" } },
{
ref: "outdoor/rucksaecke",
parent: "outdoor",
position: 0,
title: { de: "Rucksäcke" },
slug: { de: "rucksaecke" },
},
]);
// rows[i].outcome: "created" | "updated" | "unchanged" | "rejected", diffed by hash like products- One owner of a register. A Source that owns a register (
owns.registers) sends its entries, 1,000 a call, each judged on its own and diffed by hash, a logo by URL or id like a product's pictures. Akeneo keeps the brands while the editors keep the certifications: any other writer is refused withregister_not_owned. An entry stays live while a live product links it: its withdrawal names how many, and a bulk job relinks them first.
await akeneo.entries("brands", [
{
ref: "deuter",
name: { de: "Deuter" },
slug: { de: "deuter" },
image: { url: "https://pim.nordgrat.de/assets/deuter-logo.png" },
link: "https://www.deuter.com",
},
]);
await akeneo.withdraw({ register: "brands", entries: ["tatonka"] });// 3. Offers, the fast lane: no draft, no version, live within the offer lifetime.
const offers = await akeneo.offers([
{
sku: "BP-ALPIN-30-GRN",
channel: "de",
price: { amount: 12990, currency: "EUR" },
sale: {
price: { amount: 9990, currency: "EUR" },
from: "2026-11-27T00:00:00+01:00",
until: "2026-12-01T00:00:00+01:00",
},
availability: "in_stock",
deliveryDays: { min: 1, max: 3 },
},
]);
// offers.rows[i].outcome: "changed" | "unchanged" | "rejected" (with errors, such as an amount in EUR for the CHF channel)
// a row taken but probably not meant so carries warnings, such as a sale no cheaper than its price
// a counted SKU's offer sends no availability: its band follows its count
// 4. Counts, from the Source that owns stock: the units to sell as of a moment, or null to stop counting.
const erp = source({ url: "https://catalog.nordgrat.de", key: env.ORBCATALOG_ERP_KEY });
const counted = await erp.stock([
{ sku: "BP-ALPIN-30-GRN", available: 12, asOf: "2026-10-01T06:00:00+02:00" },
{ sku: "BP-ALPIN-30-RED", available: null, asOf: "2026-10-01T06:00:00+02:00" },
]);
// counted.rows[i].outcome: "changed" | "unchanged" | "rejected" (an asOf ahead, or older than the count in place)
// 5. Lifecycle.
await akeneo.discontinue(["BP-CLASSIC-22"]); // still delivered, marked, no longer sold
await akeneo.withdraw(["BP-RECALL-1"]); // gone: 404
await akeneo.live(["BP-CLASSIC-22", "BP-RECALL-1"]); // back on sale, using the last published version
await akeneo.withdraw({ categories: ["outdoor/alt"] }); // after its live children and its products, so nothing goes dark by accident
// each answers { changed, unchanged, errors }: a ref never published is an error at its pointer
// a Source that has not successfully synced a product cannot change its lifecycle: product_not_ownedProduct lifecycle rows on POST /sync/v1/publication accept state: "live" | "discontinued" | "withdrawn". live() restores delivery and sale of the last published version; it publishes no draft and creates no version. Sending the current state again is unchanged. A never-published product is refused with product_unpublished, and an editorial or handed-over product with product_editorial. Successfully synced contributors with disjoint fields may change the same product's lifecycle; an unrelated Source may not. An ordinary product sync keeps a withdrawn or discontinued product in that state: bringing it back is explicit. A withdrawn product holds none of its SKUs, so another product may take them; bringing it back claims them again, and the row is refused with sku_taken while another product holds one.
Read back your refs. GET /sync/v1/products (refs()) returns a private, Source-authenticated list of refs this Source successfully synced, including unchanged rows and every publication state. Rejected rows, other Sources' products and products handed to editors are excluded. Original bringing Sources and successful contributors both see a shared ref, once each. Pages use product creation order (not ref order or last-sync time), limit (25 by default, at most 100), and an opaque after cursor scoped to this Source. Omit after for the first page; the last page has no next. This is a live read, not a snapshot: later-created products may appear while paging.
const broughtRefs = new Set<string>();
let brought = await akeneo.refs({ limit: 100 });
for (;;) {
for (const ref of brought.data) broughtRefs.add(ref);
if (brought.next === undefined) break;
brought = await akeneo.refs({ limit: 100, after: brought.next });
}Every write call carries an Idempotency-Key of its own. After a 429 or a 5xx, or a 409 request_in_progress while the first request with that key still runs, the client sends it again, a few times with backoff, so a call the catalog finished but could not answer is answered from the first one and never written twice. A call refused as a whole (a row of the wrong shape) throws CatalogError; the calls before it stand, and a rerun finds their rows unchanged.
Keep images on an existing CDN
Use linkMedia() instead of media() when your images and their resized versions are already hosted. The Source supplies their metadata; Catalog does not fetch, verify the bytes, copy, resize or proxy these files. No bucket credentials or provider-specific configuration are needed.
const linked = await akeneo.linkMedia([
{
url: "https://cdn.nordgrat.de/products/alpin-green.jpg",
width: 1200,
height: 900,
contentType: "image/jpeg",
renditions: [
{ url: "https://cdn.nordgrat.de/products/alpin-green-320.jpg", width: 320, height: 240 },
{ url: "https://cdn.nordgrat.de/products/alpin-green-640.jpg", width: 640, height: 480 },
],
},
]);Each row is accepted or rejected as with media(). Accepted links are immediately available with outcome linked in images(); there is no fetch queue to wait for. Products, category pictures and register images name the original URL or returned media id as usual. Library delivery, product pages, cards, Search and Cart all use the exact external addresses. A browser requests the CDN directly: there is no Catalog or storefront Worker hop, redirect or dynamic transform. Cloudflare CDN, CloudFront, Bunny and other hosts use the same contract; the URLs, not Catalog, choose the provider.
The original is the largest available file, not necessarily the camera original. Up to 20 existing renditions may have distinct smaller widths and the same proportions, allowing one pixel of rounding. Catalog selects the smallest existing size that meets the requested width, or the original when none does. It generates no missing sizes and never enlarges a file. Omitting renditions serves the original alone, even if managed images use Cloudflare transformations. Optional bytes is the original's byte count; unknown sizes remain null, not an invented count. The Source is responsible for correct dimensions, format, URLs and actual image availability.
Use stable public HTTPS URLs. Local/private literal addresses, embedded credentials, temporary signed-access parameters and URL fragments are refused for originals and renditions. Configure the host's cache policy and retain the files independently of the previous shop. External cache freshness, invalidation and availability remain that host's responsibility; Catalog cannot purge another provider's browser or CDN cache. For replacements, prefer versioned URLs and resync the affected products/categories/entries. A changed descriptor registers a new media identity; existing published documents retain their previous image reference until explicitly synced or edited.
The library keeps the normal identity, metadata edits and use/delete protection. Repeating the same metadata, in any rendition order, keeps the id. Catalog refuses byte replacement of external files with media_external; deleting an unused link removes only its library reference, never the external object. Managed uploads and background media() imports continue to work alongside links. This public-reference mode is separate from connecting an existing private bucket.
Register selected private objects
Use registerMedia() for selected originals already in the merchant's configured private store. The deployment must grant this Source ID the exact keys or explicit directory prefixes it may register; product-field ownership (owns.media) is not storage authority. No grants means no registration. Configure private storage and grants on the server, never in a Source request.
Registration consents to eventual public library delivery of the selected image. Grant only image namespaces intended for shoppers, not a private document or backup namespace. A registered file joins the same library; it is not a private attachment with a separate reader permission.
const privateImages = await akeneo.registerMedia([
{ key: "products/alpin-green.jpg", width: 1200, height: 900, contentType: "image/jpeg" },
]);
for (const row of privateImages.rows) {
if (row.outcome === "rejected") {
report(row.key, row.errors);
continue;
}
await akeneo.products([{ ref: "BP-ALPIN-30", type: "backpack", media: [{ media: row.media }] }]);
}PUT /sync/v1/media/objects takes at most 50 NDJSON entries per call; the client splits larger arrays and adjusts error pointers to the caller's full array. A manifest is those same rows, not a bucket scan or a URL Catalog fetches. Invalid request shapes fail the call as with other Source methods. Each well-shaped entry is independently registered, unchanged or rejected; successful entries include media, width and height. Missing, forbidden, unsupported, oversized, unreachable or conflicting objects do not prevent other entries from registering. Retry refused entries after correcting the cause. An empty client array sends no request.
Authorization happens before any storage access. Catalog reads only each allowed object's HEAD metadata, with three concurrent checks and an eight-second metadata-check budget per call. It never fetches image bytes, copies originals, lists a selection, or asks a remote manifest URL. Storage operations already started may finish after that wait budget. HEAD supplies type and byte count, between one byte and 20 MB; the supplied format must agree. Dimensions are Source-supplied, not byte-verified, and must fit the configured transform. The Source remains responsible for their accuracy. Provider failures are redacted and do not become missing-object results.
The same merchant store and exact key keep one library ID across Sources, concurrent/repeated registration, unregistering and eventual library forgetting. Keys are opaque, case-sensitive data: spaces, Unicode and literal %, +, ?, # and & are not URL syntax and are not normalized. Unsupported ./.. segments, backslashes, malformed Unicode and keys over 1,024 UTF-8 bytes are refused. A registered object has no verified content digest; an opaque storage ETag is never treated as SHA-256. Managed uploads keep their existing content deduplication. Different metadata for an existing registration is rejected rather than silently changing its geometry. Registration does not refresh replaced bytes or grant management authority.
Products, category images and register images use the returned media ID, never the private key, store, credential or presigned URL. Library and product responses do not expose private locators. Library names start as “Registered image” and can be renamed. Ordinary byte replacement is refused with media_readonly before staging an upload. An authorized staff editor may explicitly Use owned copy: new owned bytes replace what that same library ID delivers, without changing any original bytes or existing uses. Sources cannot grant management or perform this action. See owned replacement and freshness.
After editorial adoption, repeating registerMedia() for the original key returns the current owned ID and dimensions, without comparing original metadata against the replacement. Resends cannot undo adoption. During the undo period they restore the owned file, not the original. After final forgetting, registration is rejected with media_metadata_conflict rather than resurrecting raw bytes; the durable mapping remembers adoption. Unregistering and forgetting never delete the registered original.
Delivery boundary: the existing media task installs a protected locator before stable original/rendition URLs and library thumbnails can serve registered private bytes, without a Postgres read per image. Replacements use a candidate policy of 30 seconds in browsers and at the edge, with explicit zero stale windows; the conservative 60-second cache budget starts after successful byte/locator installation, not the asynchronous library write. Warm-browser and real-provider freshness measurements remain separate acceptance work. Public linkMedia() references keep their exact direct URLs, without a proxy, redirect or extra transform, and their host owns freshness.
Prices are a ledger. A push's price is this Source's base from now on, its sale a reduced price during the window; both replace only what this Source sent before. A push that repeats an entry leaves it as it was, so a partial push never moves its base ahead of another Source's. A sale an editor set in the panel, or another Source's prices, stay where they are: a sale beats a base while it is below the base in force (a sale that is not cheaper is no sale, and the push is warned), and among one kind the later entry wins. The price a shopper pays is computed at each read, so the sale above starts at midnight on 27 November and ends at midnight on 1 December to the second, with nothing running then.
Stock is a count, in private. A SKU may have one count, shared by every Channel's offer of it: the units to sell as of a moment. An editor sets it beside the product's offers, unless one Source owns Stock in Connections; then only that Source pushes counts, any other is refused with stock_not_owned, and the panel shows the count read-only. The catalog keeps OrbCart's holds and the orders they book against it and derives the band from what is left: above the owner's threshold (Settings → Stock, 5 by default) in_stock, from one to it limited, at none out_of_stock. A held unit is not sold yet, so a checkout never moves the band; an order or a new count that moves it writes it into each of the SKU's offers, with the offer.changed every reader already follows. A SKU without a count is never limited and keeps the band its offers send; a SKU sold past zero (preorder, backorder) keeps a band and no count. No public read, feed entry or change ever shows a count, a hold or an order, only the band.
Imports without code. In the panel: drop a CSV, JSON Lines or XLSX file, map its columns to attributes (the panel suggests by key and label), and see the dry run: 12,480 unchanged, 310 changed, 22 new, 4 invalid, each change as a field diff. Apply runs exactly that as a job with progress and one-click undo; a product someone changed after the dry run is skipped and listed, never changed on the strength of a preview it no longer matches. An import is an editor's edit: the products it makes are the editors' in every field, and a line is refused only for a product a Source brought, where it changes a field that Source owns.
Staff product handover
@orbcatalog/client/products accepts an authenticated staff fetch, not a Source key. In the admin, use the module API's authenticated fetch and Catalog base URL. It uses the public management contracts, parses responses and retries transient failures with the same key and body.
import { products } from "@orbcatalog/client/products";
import type { Fetch } from "@orbcatalog/client";
async function handToEditors(staffFetch: Fetch, ref: string, idempotencyKey: string) {
const staffProducts = products({ url: "https://catalog.nordgrat.de", fetch: staffFetch });
const found = await staffProducts.view(ref);
if (found.status !== "found") return found;
const answer = await staffProducts.handover(
ref,
{ basedOn: found.view.draft.revision },
{ idempotencyKey },
);
if (answer.status === "ok") return answer.body; // revision, ownership: "editorial", handover audit
return answer.status; // draft_stale: reload/review; product_not_found: stop
}The wire call is POST /panel/products/{ref}/handover, { basedOn }, with Idempotency-Key. Products edit is required. A repeated handover on the current editorial revision is a no-op. The same key/body returns the original result, even after later edits, within the catalog's 24-hour idempotency window; a different body under that key throws CatalogError with idempotency_key_reused. After that window, the expected revision and existing audit still prevent a second transition. Unauthenticated, read-only and Source callers cannot hand products over. Nothing is published.
Move a product to another Type
The same client previews and makes a Type change. The preview writes nothing; the change writes only a draft of the new Type, which a whole-draft publish takes live.
import { products } from "@orbcatalog/client/products";
import type { Fetch } from "@orbcatalog/client";
async function moveToType(staffFetch: Fetch, ref: string, type: string, idempotencyKey: string) {
const staffProducts = products({ url: "https://catalog.nordgrat.de", fetch: staffFetch });
const found = await staffProducts.view(ref);
if (found.status !== "found") return found.status;
const change = { basedOn: found.view.draft.revision, type };
const preview = await staffProducts.previewTypeChange(ref, change);
if (preview.status !== "ok") return preview.status; // field_owned: hand it over first
const { dropped, kept, check } = preview.body; // what goes away, what stays on the variants
if (check.result !== "ready") return check; // what the new Type requires and the product lacks
const changed = await staffProducts.changeType(ref, change, { idempotencyKey });
return changed.status === "ok"
? { revision: changed.body.revision, dropped, kept }
: changed.status;
}The wire calls are POST /panel/products/{ref}/type/preview (Products view) and POST /panel/products/{ref}/type (Products edit, Idempotency-Key), both with { basedOn, type, axes? }. axes names each variant's option on the new Type's axes by variant id and attribute id; an option a variant holds on the same attribute is kept without it. The preview answers { basedOn, type, dropped, kept, moved, check }: dropped and kept are { field, value } with field a draft field path, moved the storefront addresses the new Type's page template changes, and check the publish check in the live version's languages. The change answers { revision }; a basis other than the draft's revision is draft_stale, a Source's product field_owned, an unknown Type or option body_invalid. A save based on a revision before the change is stale as a whole. Changes, webhooks, OrbSearch and OrbCart see nothing until the publish, which is the usual product.published.
An editor's product is withdrawn and brought back with staffProducts.changePublication(ref, "withdrawn" | "live", { idempotencyKey }), on the wire POST /panel/products/{ref}/publication (Products edit, Idempotency-Key) with { state }, answered { state }. Withdrawing is the usual product.withdrawn, bringing back the usual product.published of the live version. A withdrawn product holds none of its SKUs, so moving a SKU to another product is: withdraw the old one, then save the SKU on the new one. Bringing back claims the SKUs again and is sku_taken with { sku, ref } while another product holds one. A Source's product is field_owned, a never-published one product_unpublished.
The same staff client exposes saveDraft(ref, { basedOn, edits }, { idempotencyKey }). Set a variant override with { op: "set", path: { at: "variant", variant: variantId, field: "appointments" }, value: completeNeeds }; remove it with { op: "clear", path: samePath }. This only changes the draft; publish separately through the native product workflow.
Move your screens to the admin's design system
What changed in @orbcommerce/ui, how an old part becomes a new one, the rules a screen of your own follows, and how to check it with the audit.
Follow the catalog's changes
The change feed for exports and anything that wants increments, and signed webhooks.