Skip to content

Build a store in an afternoon

This guide starts with an AdonisJS 7 application and ends with a persisted order. It uses SQLite and the manual payment driver so every step runs locally.

This guide starts with an AdonisJS 7 application and ends with a persisted order. It uses SQLite and the manual payment driver so every step runs locally. Swap Stripe in after the flow works.

1. Create or install

For a new application, run the interactive scaffolder:

pnpm create adocommerce@latest my-store

It delegates to the official AdonisJS generator, always installs @adocommercekit/core, lets you select the optional packages, then runs their configurators in dependency order. The admin panel requires the React starter and automatically selects admin-api; WhatsApp automatically selects the Indonesian support package. PostgreSQL and MySQL projects are configured but are not migrated by default because working credentials are required.

For a reproducible non-interactive scaffold:

pnpm create adocommerce@latest my-store \
  --kit=react \
  --database=postgres \
  --packages=storefront-api,admin,promotions,stripe \
  --currency=USD \
  --no-migrate \
  --yes

Run pnpm create adocommerce@latest --help for every package key and option.

--kit=api creates the application at the project root; --kit=api-monorepo targets apps/backend. Run Ace and commerce configuration from that application directory. Optional keys include store-credit and engagement; explicit --packages= selects no extras (core is always installed). Without a recognized package-manager user agent, the scaffolder uses npm; select --package-manager=pnpm explicitly when needed.

--dry-run prints the plan without creating files. If the upstream creation step fails, the new destination is removed so the original command can be retried. A later install/configuration failure retains the application and prints the remaining failed-operation plan. Re-run the original options with --resume to skip creation and repeat installation/configuration; it requires the existing application’s ace.js and is not a promise to skip previously completed configuration.

Without explicit options, --yes selects hypermedia, SQLite, storefront-api plus core, commerce_, USD, Git initialization, and migrations. Available starter kits are hypermedia, react, vue, api, and api-monorepo; --packages=none also selects core alone. When admin-api is selected, the scaffolder leaves doctor as a next step: map the generated host abilities first. For the admin panel, also add the Tailwind v4 Vite plugin as directed by the configurator. Provider credentials must be supplied before enabling external integrations.

For an existing application, the requirements are Node.js 24+, AdonisJS 7, Lucid 22, and a configured database connection. Adocommerce Kit is prerelease software. The workspace manifests currently use the lockstep 1.3.0-0 version; install matching exact versions of every @adocommercekit/* package in a controlled deployment, and read stability and compatibility before depending on a surface.

pnpm add @adocommercekit/core @adocommercekit/storefront-api
node ace configure @adocommercekit/core
node ace configure @adocommercekit/storefront-api
node ace migration:run

@adocommercekit/core adds its provider and commands, writes config/commerce.ts, and publishes migrations into database/migrations. @adocommercekit/storefront-api publishes controllers, validators, middleware, and the /api/commerce route file. Nothing is mounted invisibly from node_modules.

Commit the generated files. They are part of your application.

2. Check the installation

node ace commerce:doctor

A healthy result confirms required tables, payment driver capabilities, driver health checks, and inventory reservation totals. If a deferred or COD provider is registered, doctor also requires retrieveIntent and, in production, jobs.dispatcher: 'queue'. Application boot has already validated configuration and the model registry. Fix doctor errors before seeding.

3. Seed a catalog

node ace commerce:seed:demo

The demo seeder is idempotent. It creates web/retail channels, a Field Supply category tree, outdoor products with variants and descriptions, USD/EUR/IDR prices, multi-location inventory, and flat-rate shipping methods. In the playground, follow with node ace commerce:id:seed:demo (or pnpm --filter playground demo:reset) for Indonesian customers, orders, payments, shipments, and cart funnel data.

Start Adonis and inspect the storefront contract:

node ace serve --hmr
curl http://localhost:3333/api/commerce/products

Each variant includes a serialized price and an availability object. Product controllers preload every relationship used by the transformer; transformers never issue queries.

4. Create a cart

Keep the cookie jar because the default sessionCartToken() strategy stores the anonymous cart token in the session.

curl -c .cart-cookie -b .cart-cookie \
  http://localhost:3333/api/commerce/cart

Copy a variantId from the product response, then add it:

curl -c .cart-cookie -b .cart-cookie \
  -H 'content-type: application/json' \
  -d '{"variantId":"<variant-id>","quantity":2}' \
  http://localhost:3333/api/commerce/cart/lines

If Shield protects your API mutations, expose its XSRF cookie and send X-XSRF-TOKEN, or exempt token-authenticated API routes in config/shield.ts. The generated payment webhook route is excluded because external providers cannot send a CSRF token.

5. Add checkout details

curl -X PUT -c .cart-cookie -b .cart-cookie \
  -H 'content-type: application/json' \
  -d '{"email":"buyer@example.com"}' \
  http://localhost:3333/api/commerce/cart/email

curl -X PUT -c .cart-cookie -b .cart-cookie \
  -H 'content-type: application/json' \
  -d '{"shipping":{"firstName":"Ari","lastName":"Stone","line1":"18 Market Street","city":"Portland","region":"OR","postalCode":"97205","countryCode":"US"}}' \
  http://localhost:3333/api/commerce/cart/addresses

List eligible shipping methods, then select one:

curl -c .cart-cookie -b .cart-cookie \
  http://localhost:3333/api/commerce/cart/shipping-methods

curl -X PUT -c .cart-cookie -b .cart-cookie \
  -H 'content-type: application/json' \
  -d '{"methodId":"<shipping-method-id>"}' \
  http://localhost:3333/api/commerce/cart/shipping-method

6. Place the first order

curl -X POST -c .cart-cookie -b .cart-cookie \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: tutorial-order-001' \
  -d '{"payment":{"method":"manual"}}' \
  http://localhost:3333/api/commerce/checkout

The response is 201 with the storefront order transformer and a seven-day accessToken. Repeating the same request with the same key returns the same order. Reusing the key with a different payload returns E_IDEMPOTENCY_CONFLICT.

Read the order without an account:

curl 'http://localhost:3333/api/commerce/orders/<order-number>?token=<access-token>'

The generated controller also authorizes an authenticated user when the order’s customer record has a matching userId. Signed access tokens remain available for guest orders.

7. Move to Stripe

Install and configure the Stripe package:

pnpm add @adocommercekit/stripe
node ace configure @adocommercekit/stripe

Register stripe() under payments.methods in config/commerce.ts, provide the server key and webhook secret through Adonis environment validation, and point Stripe at:

POST /api/commerce/webhooks/payments/stripe

Do not parse and re-stringify webhook JSON. The published raw-body middleware reads Adonis’s preserved request body and passes those exact UTF-8 bytes to the provider verifier.

The generated checkout controller handles synchronous authorization. It does not publish a complete 3DS/SCA client-confirmation flow. Follow the Stripe guide, including its SCA limitation, before enabling Stripe in production.

Selling in Indonesia instead? @adocommercekit/midtrans and @adocommercekit/xendit implement the same payment port with deferred channels such as QRIS, virtual accounts, and e-wallets, and @adocommercekit/id adds kode-unik manual transfer. Those flows return an order in pending_payment with payment instructions rather than an immediate authorization, and production use requires jobs.dispatcher: 'queue'. Start from packages and imports.

8. Upgrade generated files

node ace commerce:upgrade

The command reports add, update, noop, conflict, kept, removed-by-host, unconfigured, or error. Conflicts are never overwritten: incoming source and three-way-merge instructions are staged under .commercekit/incoming. Review advisories and keep the incoming stock source as the publication baseline after merging; see the upgrade procedure and merge troubleshooting.

Next steps

Navigation

Type to search…

↑↓ navigate↵ selectEsc close