ORBCART DOCUMENTATION

Deployment

Deploy a test environment to your Cloudflare account, step by step.

OrbCart runs in your Cloudflare account. There is no OrbCart server in between.

What runs where

PieceWhat it does
One Worker per environmentServes the API and calls your systems.
Durable ObjectsHold Carts, Payments and Orders. The source of truth.
D1 (optional)The Order list for the Admin API and the Explorer.
Cron triggerThe daily EU VAT import, if you use eu-standard.
Your storefrontAnywhere you like. Only the commerce Worker needs Cloudflare.

test and live are separate environments with separate keys and data.

Deploy a test environment

Until orbcart deploy exists, a test environment is a few Wrangler commands. Run them from your commerce Worker's directory. examples/nordgrat is the reference.

Deploy the Worker

pnpm exec wrangler deploy --name shop-commerce-test

The first deploy creates the D1 database for the Order list. Apply its schema, now and after every runtime update:

pnpm exec wrangler d1 migrations apply PROJECTION --remote

Set the root secret

Generated and piped straight in, so it never appears on screen or in your history:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' | pnpm exec wrangler secret put ROOT_SECRET --name shop-commerce-test

Set your provider keys

Only for the providers your Channels use. Which keys →

pnpm exec wrangler secret put STRIPE_SECRET_KEY --name shop-commerce-test
pnpm exec wrangler secret put STRIPE_PUBLISHABLE_KEY --name shop-commerce-test
pnpm exec wrangler secret put STRIPE_WEBHOOK_SECRET --name shop-commerce-test

Until every required secret is set, the Worker answers each request with internal_error. pnpm exec wrangler tail --name shop-commerce-test shows what's missing.

Point the webhooks at it

ProviderURL
Stripehttps://shop-commerce-test.<account>.workers.dev/webhooks/stripe
Adyenhttps://shop-commerce-test.<account>.workers.dev/webhooks/adyen
PayPalhttps://shop-commerce-test.<account>.workers.dev/webhooks/paypal

Issue keys for the storefront

pnpm exec orbcart keys issue --env test --channel de --url https://shop-commerce-test.<account>.workers.dev

This writes the URL, a publishable key and a secret key to .orbcart/keys/test-de.env. Give the storefront what it needs from there.

Prime EU VAT

Only for Channels with tax: "eu-standard":

pnpm exec orbcart tax sync --env test

Open the Explorer to your team

pnpm exec orbcart access setup --env test --host shop-commerce-test.<account>.workers.dev --allow @example.com
pnpm exec orbcart members add you@example.com --role owner --env test

The Explorer is at https://<host>/explorer. CLI →

Connect the storefront

  • Add the storefront's origin to the Channel's origins and set returnUrl to its return page. Then deploy the Worker again.
  • Give the storefront ORBCART_URL and ORBCART_PUBLISHABLE_KEY. Only a server-side part gets ORBCART_SECRET_KEY.
  • With Apple Pay, register the storefront's domain with your provider. Express →

Updating

pnpm exec wrangler deploy --name shop-commerce-test
pnpm exec wrangler d1 migrations apply PROJECTION --remote

Secrets stay on the Worker between deploys. Open Carts keep working: a Cart remembers its Channel, so don't rename or remove a Channel that still has Carts.

Checklist before real money

  • Everything on the security checklist is done: keys, secrets, origins, webhooks.
  • orbcart tax status shows today in availableOn, if you use EU VAT.
  • deliverOrder deduplicates by order.id.
  • Every Channel names its withdrawal_policy and privacy_policy in legal. Without them a live Worker serves nothing.
  • Your confirmation email and an order page are in place.

Pre-release

orbcart keys issue only supports test today. A guided live setup arrives with orbcart deploy. Check the status page before taking real orders.

On this page