ORBCOMMERCE DOCUMENTATION
OrbCart quickstart
Run the reference shop on your machine in about ten minutes. Then buy something in five lines of code.
OrbCart is the transaction layer between your storefront and your systems. You keep your product data and your storefront. OrbCart runs the Cart, the Quote, the Payment and the Order.
The fastest way to understand it is to run Nordgrat, a complete example outdoor shop that ships with the source.
Before you begin
OrbCart is pre-release. Packages are not on npm yet and the repository is not public. You need the
source checkout, Node.js 24+, pnpm (the version in package.json) and a free Stripe
test account. Just looking? Try the live demo. Nothing is charged
or shipped.
Run Nordgrat locally
Add your test keys
Create .dev.vars in the repository root. It holds the secrets of the commerce Worker.
Generate the root secret first. It protects the environment's signing keys:
openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'Nordgrat uses three payment providers. Pick the variant that matches the accounts you have:
ROOT_SECRET=paste-the-generated-value
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...Then point every method at Stripe in apps/nordgrat-cart-worker/src/commerce.ts:
// channels.de
payments: { card: "stripe", apple_pay: "stripe", google_pay: "stripe", klarna: "stripe", eps: "stripe" },
// channels.ch
payments: { card: "stripe", twint: "stripe" },The storefront also needs a secret for its own sign-in. Generate a second value
with the same command and put it in apps/nordgrat-cart/.dev.vars:
BETTER_AUTH_SECRET=another-generated-valueBoth files are ignored by Git. Never put their contents in browser code, URLs or logs.
Start the shop
Run each command in its own terminal, from the repository root:
pnpm --filter @orbcart/example-nordgrat systemspnpm --filter @orbcart/demo commercepnpm --filter @orbcart/demo devstripe listen --latest --all-snapshot --forward-to localhost:8787/webhooks/stripeCopy the signing secret that stripe listen prints into STRIPE_WEBHOOK_SECRET
and restart terminal 2. You only do this once.
Buy something
Open localhost:5173/en. Add a backpack, open the Cart and check out with made-up details and a test card.
Open Behind the scenes at any time. It shows every SDK call and the server's answer.
What did terminal 2 just do?
pnpm --filter @orbcart/demo commerce runs orbcart dev. It starts the commerce
Worker on port 8787 and writes ORBCART_URL, a publishable key per market and the secret key into
apps/nordgrat-cart/.dev.vars. These are OrbCart keys, not Stripe keys.
A purchase in five lines
This is the whole purchase. shipTo is the buyer's address and payment is the
card field you mounted on the page:
import { createCommerce } from "@orbcart/client";
const commerce = createCommerce({ url: "http://localhost:8787", key: "pk_test_..." });
const cart = await commerce.cart();
await cart.add("BACKPACK-30-GREEN");
const quote = await cart.quote({ shipTo, contact: { email: "anna@example.com" } });
const result = await quote.pay({ payment });When the card goes through, result.status is "ordered" and result.order.number
looks like NG-2026-004711. The rest of these docs explain each line, and
every other outcome. How it works
follows the same purchase through the server.
Where things live
| Path | What you change there |
|---|---|
apps/nordgrat-cart-worker/src/commerce.ts | Markets, shipping, payment methods and discount codes. |
apps/nordgrat-cart-worker/src/offers.ts | How prices and product facts reach OrbCart. |
apps/nordgrat-cart-worker/src/systems.ts | Stock checks and the hand-off to the ERP. |
apps/nordgrat-cart/app/shop/checkout-labels.tsx | The checkout's wording. |
Useful commands
| Command | What it does |
|---|---|
pnpm check | Select and run affected validation. |
pnpm check:plan | Preview the affected validation scope. |
pnpm check:full | The lead's complete integration gate. |
pnpm --filter @orbcommerce/docs dev | These docs on localhost:4200/docs. |
Troubleshooting
The Worker answers every request with 500. A provider in payments is missing
its keys. The Worker log names the missing bindings. Add them or map the method to
another provider.
A payment stays "processing". stripe listen is not running, or its secret is
not in .dev.vars. Without webhooks, OrbCart never learns the final answer.
origin_not_allowed in the browser. Your storefront runs on a host that is not
in the Channel's origins. Localhost is always allowed in test.