# 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:

```ts title="src/worker.ts"
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.

<Callout title="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_error`, and the Worker log names the reason. It never fails only the first buyer.
</Callout>

## 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 →](/integrations)             |
| `inventory`    |          | Check or reserve stock. [Inventory →](/integrations/inventory), in [another system →](/integrations/remote-contracts)                      |
| `deliverOrder` |          | Hand every new Order to your ERP. [Inventory →](/integrations/inventory#hand-orders-to-your-erp)                                           |
| `fetchOrders`  |          | `true` when your ERP fetches Orders instead, never with `deliverOrder`. [Fetching →](/integrations/inventory#or-let-your-erp-fetch-orders) |
| `events`       |          | Receivers of Order events by name, such as `mails`: a function, an HTTP endpoint or a Service Binding. [Events →](/integrations/events)    |
| `orderNumbers` |          | Your prefix, such as `{ prefix: "NG" }` for `NG-2026-004711`.                                                                              |
| `identity`     |          | Accept your shop's login. [Signed-in buyers →](/integrations/identity)                                                                     |
| `extensions`   |          | Your own typed values on Lines or the Cart. [Extensions →](/commerce/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 →](/integrations/tax)                                                                                                              |
| `taxRounding`         | `"total"`                                 | `"line"` if your ERP rounds per Line.                                                                                                                         |
| `shipping`            | `{ DE: [...] }`                           | Countries you ship to and how. [Shipping →](/commerce/shipping)                                                                                               |
| `payments`            | `{ card: "stripe" }`                      | Payment methods and their provider. [Payments →](/payments)                                                                                                   |
| `discounts`           | `[{ id, code, percentage }]`              | Built-in discount codes. [Discounts →](/commerce/discounts)                                                                                                   |
| `contactFields`       | `{ phone: "optional" }`                   | Extra contact fields beyond the email address.                                                                                                                |
| `abandonedAfterHours` | `24`                                      | How long a Cart may stand still before `cart.abandoned`. [Events →](/integrations/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 →](/integrations/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 →](/commerce/order-page)                                              |
| `agents`              | `{ continueUrl }`                         | Let AI agents check out. [AI agents →](/agents)                                                                                                               |
| `legal`               | `{ withdrawal_policy: { url, version } }` | Your legal texts, linked at the order button and named in every Quote. [Legal texts ↓](#legal)                                                                |

### 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()`](/commerce/quotes#5-return-from-a-redirect).

### contactFields

The checkout always asks for an email address. Ask for more only if you need it:

```ts members="ChannelConfig"
contactFields: { phone: "optional" },
```

A shipping method that needs a field makes it required for that method alone.
See [`requires`](/commerce/shipping#rule-options).

### 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.

```ts members="ChannelConfig"
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:

```ts members="CommerceConfig"
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`](/sdks/cli) 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 |
| `events` receivers             | 10 seconds |

Need more time? Attach the function with `run` and `timeoutMs`:

```ts members="CommerceConfig"
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. The environment's public address; the `source` of its events. |
| `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 →](/payments)      |
| `PROJECTION`                                              | D1     | Optional. Powers the Order list.                                        |

Never change `ROOT_SECRET` on a running environment. The environment's keys
derive from it.

`examples/nordgrat/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](/extend).

[Connect your prices and products →](/integrations)