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
| Piece | What it does |
|---|---|
| One Worker per environment | Serves the API and calls your systems. |
| Durable Objects | Hold Carts, Payments and Orders. The source of truth. |
| D1 (optional) | The Order list for the Admin API and the Explorer. |
| Cron trigger | The daily EU VAT import, if you use eu-standard. |
| Your storefront | Anywhere 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-testThe 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 --remoteSet 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-testSet 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-testUntil 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
| Provider | URL |
|---|---|
| Stripe | https://shop-commerce-test.<account>.workers.dev/webhooks/stripe |
| Adyen | https://shop-commerce-test.<account>.workers.dev/webhooks/adyen |
| PayPal | https://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.devThis writes the URL, a publishable key and a secret key to
.orbcart/keys/test-de.env. Give the storefront what it needs from there.
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 testThe Explorer is at https://<host>/explorer. CLI →
Connect the storefront
- Add the storefront's origin to the Channel's
originsand setreturnUrlto its return page. Then deploy the Worker again. - Give the storefront
ORBCART_URLandORBCART_PUBLISHABLE_KEY. Only a server-side part getsORBCART_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 --remoteSecrets 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 statusshows today inavailableOn, if you use EU VAT. -
deliverOrderdeduplicates byorder.id. - Every Channel names its
withdrawal_policyandprivacy_policyinlegal. Without them aliveWorker 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.