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

<Callout title="Before you begin">
  OrbCart is pre-release. Packages are not on npm yet and the repository is not public. You need the
  source checkout, &#x2A;*Node.js 24+**, **pnpm** (the version in `package.json`) and a free **Stripe**
  test account. Just looking? [Try the live demo](https://demo.orbcart.dev/en). Nothing is charged
  or shipped.
</Callout>

## Run Nordgrat locally

### Install the workspace

From the repository root:

```sh
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:

```sh
openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'
```

Nordgrat uses three payment providers. Pick the variant that matches the accounts you have:

<Tab value="Stripe only">
  ```dotenv title=".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 `examples/nordgrat/src/commerce.ts`:

  ```ts title="examples/nordgrat/src/commerce.ts" worker alternatives members="ChannelConfig"
  // channels.de
  payments: { card: "stripe", apple_pay: "stripe", google_pay: "stripe", klarna: "stripe", eps: "stripe" },

  // channels.ch
  payments: { card: "stripe", twint: "stripe" },
  ```
</Tab>

<Tab value="Stripe, Adyen and PayPal">
  ```dotenv title=".dev.vars"
  ROOT_SECRET=paste-the-generated-value

  STRIPE_SECRET_KEY=sk_test_...
  STRIPE_PUBLISHABLE_KEY=pk_test_...
  STRIPE_WEBHOOK_SECRET=whsec_...

  ADYEN_API_KEY=...
  ADYEN_CLIENT_KEY=test_...
  ADYEN_MERCHANT_ACCOUNT=...
  ADYEN_HMAC_KEY=...

  PAYPAL_CLIENT_ID=...
  PAYPAL_CLIENT_SECRET=...
  PAYPAL_WEBHOOK_ID=...
  ```

  [Payments](/payments) explains where each value comes from.
</Tab>

The storefront also needs a secret for its own sign-in. Generate a second value
with the same command and put it in `apps/demo/.dev.vars`:

```dotenv title="apps/demo/.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:

```sh title="Terminal 1 · the merchant's pricing and ERP"
pnpm --filter @orbcart/example-nordgrat systems
```

```sh title="Terminal 2 · OrbCart"
pnpm --filter @orbcart/demo commerce
```

```sh title="Terminal 3 · the storefront"
pnpm --filter @orbcart/demo dev
```

```sh title="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](http://localhost:5173/en). Add a backpack, open the
Cart and check out with made-up details and a [test card](/payments/test-payments).

Open **Behind the scenes** at any time. It shows every SDK call and the server's answer.

<Callout title="What did terminal 2 just do?">
  `pnpm --filter @orbcart/demo commerce` runs [`orbcart dev`](/sdks/cli). It starts the commerce
  Worker on port 8787 and writes `ORBCART_URL`, a publishable key per market and the secret key into
  `apps/demo/.dev.vars`. These are OrbCart keys, not Stripe keys.
</Callout>

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

```ts
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](/commerce/quotes#4-place-the-order). [How it works](/how-it-works)
follows the same purchase through the server.

## Where things live

| Path                                     | What you change there                                  |
| ---------------------------------------- | ------------------------------------------------------ |
| `examples/nordgrat/src/commerce.ts`      | Markets, shipping, payment methods and discount codes. |
| `examples/nordgrat/src/offers.ts`        | How prices and product facts reach OrbCart.            |
| `examples/nordgrat/src/systems.ts`       | Stock checks and the hand-off to the ERP.              |
| `apps/demo/app/shop/checkout-labels.tsx` | The checkout's wording.                                |

## Useful commands

| Command                                                   | What it does                                           |
| --------------------------------------------------------- | ------------------------------------------------------ |
| `pnpm check`                                              | Types, lint, format, builds and every test.            |
| `pnpm test`                                               | All tests once.                                        |
| `pnpm test:watch`                                         | Tests in watch mode.                                   |
| `pnpm --filter @orbcart/example-nordgrat exec vitest run` | Only Nordgrat's purchase and scenario tests.           |
| `pnpm --filter @orbcart/docs dev`                         | These docs on [localhost:4200](http://localhost:4200). |

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

<Cards>
  <Card title="Concepts" href="/concepts" description="You own the catalog, OrbCart owns the purchase. The model in one page." />

  <Card title="Configuration" href="/configuration" description="One defineCommerce call describes your whole shop." />

  <Card title="Connect your data" href="/integrations" description="Write the one function OrbCart needs from you." />

  <Card title="React checkout" href="/sdks/react" description="A complete checkout in one component." />
</Cards>