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-storeIt 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 \
--yesRun 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-apinode 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:doctorA 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:demoThe 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/productsEach 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/cartCopy 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/linesIf 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/addressesList 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-method6. 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/checkoutThe 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/stripeRegister 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/stripeDo 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:upgradeThe 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
- Review every option in the configuration reference.
- Treat the REST storefront as host-owned application code.
- Learn the Ace commands for diagnostics, seeding, extension, and upgrades.
- Follow the deployment and operations guide before running more than one process or accepting real payments.
- Use troubleshooting when doctor, checkout, generated files, or webhooks fail.
- Start with Build commerce for Indonesia for regional payments, logistics, IDR and PPN, PDP operations, and WhatsApp.