Skip to Content
Get started

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

Install the workspace

From the repository root:

pnpm install

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:

.dev.vars
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:

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:

apps/nordgrat-cart/.dev.vars
BETTER_AUTH_SECRET=another-generated-value

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

Terminal 1 · the merchant's pricing and ERP
pnpm --filter @orbcart/example-nordgrat systems
Terminal 2 · OrbCart
pnpm --filter @orbcart/demo commerce
Terminal 3 · the storefront
pnpm --filter @orbcart/demo dev
Terminal 4 · Stripe webhooks
stripe listen --latest --all-snapshot --forward-to localhost:8787/webhooks/stripe

Copy 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

PathWhat you change there
apps/nordgrat-cart-worker/src/commerce.tsMarkets, shipping, payment methods and discount codes.
apps/nordgrat-cart-worker/src/offers.tsHow prices and product facts reach OrbCart.
apps/nordgrat-cart-worker/src/systems.tsStock checks and the hand-off to the ERP.
apps/nordgrat-cart/app/shop/checkout-labels.tsxThe checkout's wording.

Useful commands

CommandWhat it does
pnpm checkSelect and run affected validation.
pnpm check:planPreview the affected validation scope.
pnpm check:fullThe lead's complete integration gate.
pnpm --filter @orbcommerce/docs devThese 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.

Next steps

On this page