Walkthrough

This guide walks through the end-to-end customer flow using the default local setup. No code changes required — just env vars and running servers.

Before you startCopy Anchor Link

Ensure you have completed Installation:

• pnpm db:migrate and pnpm db:seed completed successfully
• pnpm dev running (or at least storefront :3000, checkout :3004, api :3005)
• NEXT_PUBLIC_PLATFORM_DOMAIN=localhost in .env.local, so the demo store is served at prood-demo.localhost:3000

The demo store is for browsing: the API refuses its orders with "This is a demo store, so it can't take orders." To take an order, register a store in the local dashboard, add a product with the status Active, and connect Stripe (or another provider) under Integrations. It's served at {your-store-address}.localhost:3000.

Checkout also needs Upstash Redis. Without it, checkout session creation fails.

Step 1 — Browse the storefrontCopy Anchor Link

Open http://prood-demo.localhost:3000. Bare localhost:3000 isn't a store, so it redirects to the marketing site.

The home page loads featured products and categories. Catalog data is fetched from the Commerce API and cached per tenant with Next.js Cache Components ('use cache' + tenant-scoped cache tags).

Navigate to Products to see the full catalog with search and sort.

Step 2 — Add items to the cartCopy Anchor Link

Switch to the store you registered, at {your-store-address}.localhost:3000, and click Add to cart on your product. The storefront:

1. Reads or creates a cart via the local BFF route POST /api/commerce/cart/items
2. Stores the cart ID in an HTTP-only cookie (commerce_cart_id, 30-day TTL)
3. Updates the cart drawer UI via React context

Open the cart drawer (header icon) to review items or adjust quantities.

Step 3 — Start checkoutCopy Anchor Link

Go to /checkout or click Checkout in the cart drawer.

The checkout page collects:

• Customer email and name
• Shipping address (when fulfillment requires shipping)
• Billing address (optional)

When you submit, the server action startCheckout() in apps/storefront/app/(checkout)/checkout/actions.ts:

1. Calls the API POST /v1/carts/{id}/place-order to create an order
2. Creates a checkout session on apps/checkout via POST /api/sessions
3. Redirects the browser to http://localhost:3004/c/{sessionId}

Step 4 — Complete paymentCopy Anchor Link

On the checkout app payment page:

After successful payment, you are redirected to /confirm/{sessionId} and then back to the storefront order confirmation page.

Step 5 — Verify in the dashboardCopy Anchor Link

Sign in to the merchant dashboard at http://localhost:3002.

Use the account you registered the store with.

Navigate to Orders to see the order you just placed. You can fulfill, refund, or view order details.

What happened under the hoodCopy Anchor Link

API quick testCopy Anchor Link

You can also interact with the API directly:

# Health check
curl http://localhost:3005/v1/health

# List the demo store's products (tenant from the storefront host)
curl -H "x-storefront-host: prood-demo.localhost" http://localhost:3005/v1/products

# OpenAPI spec
curl http://localhost:3005/v1/openapi.json

Browse the interactive reference at Commerce API.

Next stepsCopy Anchor Link