ORBCOMMERCE DOCUMENTATION
Configuration
One defineCommerce call describes your whole shop. Markets, shipping, payments and your systems.
Your commerce Worker is one file. It exports OrbCart's Durable Objects and one
defineCommerce call:
import { defineCommerce } from "@orbcart/runtime";
export * from "@orbcart/runtime/objects";
export default defineCommerce({
channels: {
de: {
currency: "EUR",
pricesIncludeTax: true,
locale: "de-DE",
tax: "eu-standard",
shipping: { DE: [{ id: "standard", title: "Standard delivery", price: 495 }] },
payments: { card: "stripe", paypal: "paypal" },
origins: ["https://shop.example.com"],
returnUrl: "https://shop.example.com/checkout",
},
},
offers,
});That is a working shop. Everything else is optional.
Mistakes fail at startup
OrbCart checks the whole configuration when the Worker starts. A typo or an invalid value fails
the deployment. A missing provider key or a returnUrl outside your origins fails every request
with internal, and the Worker log names the reason. It never fails only the first buyer.
Top-level options
| Option | Required | What it does |
|---|---|---|
channels | yes | Your markets by name, such as de. At least one. |
offers | yes | Prices and product facts for the Lines of a Cart. A function, an HTTP endpoint or a Service Binding. Offers → |
inventory | Check or reserve stock. Inventory →, in another system → | |
deliverOrder | Hand every new Order to your ERP. Inventory → | |
fetchOrders | true when your ERP fetches Orders instead, never with deliverOrder. Fetching → | |
events | Receivers of Order events by name, such as mails: a function, an HTTP endpoint or a Service Binding. Events → | |
orderActions | Your own actions on an Order by id, such as parcelLabel: a label, when it is offered and what it runs. Order actions → | |
orderNumbers | Your prefix, such as { prefix: "NG" } for NG-2026-004711. | |
giftCards | How gift card codes look, how long cards last, their least and most value. Gift cards → | |
identity | Accept your shop's login. Signed-in buyers → | |
extensions | Your own typed values on Lines or the Cart. Extensions → |
Channel options
A Channel is one market. Its name (de, ch, b2b) appears in keys, Carts and Orders.
| Option | Example | What it does |
|---|---|---|
currency | "EUR" | ISO 4217 code. One currency per Channel. |
pricesIncludeTax | true | true for gross prices (B2C), false for net prices (B2B). |
locale | "de-DE" | Language of Orders and confirmations. |
tax | "eu-standard" | Where tax comes from. Tax → |
taxRounding | "total" | "line" if your ERP rounds per Line. |
shipping | { DE: [...] } | Countries you ship to and how. Shipping → |
payments | { card: "stripe" } | Payment methods and their provider. Payments → |
discounts | [{ id, code, percentage }] | The discounts a Channel starts with. Discounts → |
contactFields | { phone: "optional" } | Extra contact fields beyond the email address. |
billingAddress | "required" | Require a full billing name and address, independently of delivery. Omit to keep country-only billing for nonshipping carts. |
abandonedAfterHours | 24 | How long a Cart may stand still before cart.abandoned. Events → |
expiresAfterDays | 180 | How long a Cart without an Order may stand still before it ends and is deleted, 1 to 365, longer than abandonedAfterHours. Events → |
origins | ["https://shop.example.com"] | Sites whose browsers may call the API with this Channel's key. |
returnUrl | "https://shop.example.com/checkout" | Where redirect payments send the buyer back. |
orderPage | "https://shop.example.com/orders" | Your page for an Order; its link is this address and the Order's token. The order page → |
agents | { continueUrl } | Let AI agents check out. AI agents → |
legal | { withdrawal_policy: { url, version } } | Your legal texts, linked at the order button and named in every Quote. Legal texts ↓ |
origins and returnUrl
origins lists exact origins: scheme, host and port, no path, no trailing slash.
In test, localhost is always allowed, so local development needs no entry.
returnUrl is required as soon as a method sends the buyer away, such as PayPal,
Klarna or iDEAL. It must be a page on one of your origins. That page calls
cart.resume().
contactFields
The checkout always asks for an email address. Ask for more only if you need it:
contactFields: { phone: "optional" },A shipping method that needs a field makes it required for that method alone.
See requires.
billingAddress
billingAddress: "required",The checkout requires a full name, street, city and country, plus the postal code
and region the billing country requires. cart.fields and cart.missing name
these requirements as bill_to, bill_to_postal_code and bill_to_region.
An explicit billTo is checked on its own; without one, a full shipTo also
serves as the billing address. Pickup and services still need no delivery
address. Incomplete billing prevents payment and order creation, including express.
Without this setting, nonshipping carts need only the billing country and pickup keeps its country-only destination.
legal
Your terms, withdrawal policy and privacy policy stay on your own pages. OrbCart links them beside the order button, gives them to AI agents, and names each in every Quote by version and hash, so the buyer's consent records what they saw.
import withdrawalPolicy from "./legal/widerruf.txt"; // Wrangler bundles .txt and .html as text
legal: {
terms: { url: "https://nordgrat.de/agb", version: "2026-09-01" },
withdrawal_policy: {
url: "https://nordgrat.de/widerruf",
version: "2026-06-19",
content: withdrawalPolicy, // optional: the hash is then of the wording itself
},
privacy_policy: { url: "https://nordgrat.de/datenschutz", version: "2026-05-01" },
},Change version whenever the wording changes and deploy. A Quote the buyer is looking at keeps
the version it names; the next one shows legal_updated among its changes. Texts of your own,
such as shipping_terms, work the same way.
A live Worker refuses every request until each Channel has withdrawal_policy and
privacy_policy, so a missing text shows at your deploy, never at a buyer's order button. terms
are optional. In test nothing is required.
Several markets
Each market is its own Channel with its own currency, prices and rules. Nordgrat sells in Germany and Switzerland:
channels: {
de: {
currency: "EUR",
pricesIncludeTax: true,
locale: "de-DE",
tax: "eu-standard",
shipping: { DE: [standard], AT: [standard] },
payments: { card: "adyen", paypal: "paypal", klarna: "adyen" },
},
ch: {
currency: "CHF",
pricesIncludeTax: true,
locale: "de-CH",
tax: swissVat,
shipping: { CH: [swissPost] },
payments: { card: "adyen", twint: "adyen" },
},
},Your offers function receives the Channel's currency, so it can return Swiss
prices in francs. orbcart dev writes one publishable key per Channel.
Time budgets
Every function you attach gets a time budget. When it runs out, OrbCart aborts the
call through context.signal and treats your system as unreachable.
| Function | Default |
|---|---|
offers, inventory.*, tax | 3 seconds |
deliverOrder | 30 seconds |
orderActions.*.run | 10 seconds |
events receivers | 10 seconds |
Need more time? Attach the function with run and timeoutMs:
offers: { run: (lines, context) => pricing.offers(lines, context), timeoutMs: 5_000 },Pass context.signal to your fetch calls. An aborted request then stops instead
of running in the background.
Worker settings
These live in wrangler.jsonc and as Worker secrets, not in defineCommerce.
| Name | Kind | What it is |
|---|---|---|
MERCHANT | var | Your slug, such as nordgrat. Every Quote names it. |
ENVIRONMENT | var | live, test or preview-{name}. |
PUBLIC_URL | var | Optional public API base address, including any mount path. Used for print links, OpenAPI and event schema links; event source remains its origin. |
ROOT_SECRET | secret | 32 random bytes as base64url. Every key derives from it. |
STRIPE_*, ADYEN_*, MOLLIE_*, PAYONE_*, PAYPAL_* | secret | Provider keys. Only for providers you use. Payments → |
HYPERDRIVE | Hyperdrive | Optional. Your Postgres for the lists: Orders, Carts, Events, Checkout. |
Never change ROOT_SECRET on a running environment. The environment's keys
derive from it.
apps/nordgrat-cart-worker/wrangler.jsonc is a complete, commented reference for the
bindings, Durable Objects and the Cron trigger.
Everything beyond configuration, from contracts to plugins: Extend OrbCart.