Adocommerce Kit runs inside the host AdonisJS application. The host therefore owns deployment order, database migrations, HTTP scaling, queue workers, logs, metrics, and backups.
Production baseline
Before the first production deployment:
- use Node.js 24 or newer and a supported Lucid database;
- pin the same exact beta version of every
@adocommercekit/*package; - commit
config/commerce.ts, published migrations, storefront files, and.commercekit/publications; - replace the manual payment method unless offline payment is intentional;
- configure a shared queue dispatcher for multiple application instances;
- bind a shared rate-limit store for multiple instances instead of the default in-process store;
- configure HTTPS, trusted proxy behavior, database backups, and secret storage;
- exercise checkout, payment, webhook, and refund behavior in the target environment.
Deployment sequence
A conservative deployment runs in this order:
- Build and test the exact commit and lockfile that will deploy.
- Back up the database according to the database provider’s recovery procedure.
- Run
node ace migration:runonce from a release task. - Start or roll out the new application and queue workers.
- Run
node ace commerce:doctoragainst the deployed configuration and database. - Exercise a catalog read and a non-destructive cart request.
- Verify maintenance jobs and payment webhooks are being processed.
Do not run the package configurators on every application boot. Run them during development, review their output, and deploy the generated files with the application.
Health checks
Structural check
node ace commerce:doctorUse the doctor command after install, after configuration changes, after package upgrades, and as a release verification task. Application boot validates configuration and the model registry; the command then checks required tables, payment driver capabilities, and inventory reservation totals.
Doctor also warns about existing outbound destinations when the outbox is disabled, and old Stripe drivers that assume exponent 2 for currencies with a different core exponent and lack scaling support. Enable durable delivery or deactivate destinations as appropriate; upgrade Stripe rather than altering recorded money to hide a warning.
A doctor failure should fail the release. It is a diagnostic command, not an HTTP liveness endpoint; add a small host-owned endpoint for your platform if one is required.
Runtime smoke
With the optional storefront API installed:
curl --fail-with-body https://your-store.example/api/commerce/products?perPage=1
curl --fail-with-body -c /tmp/commerce-cookie \
https://your-store.example/api/commerce/cartThe second request may create an anonymous cart. Use an isolated environment or remove the cart afterward if synthetic data is undesirable.
Commerce CLI
Adocommerce Kit extends the host application’s Ace console. Run commands as
node ace commerce:*; there is no separate global executable or second
configuration context.
Setup and automation
commerce:setup inspects the installed @adocommercekit/* packages without
booting the application. It checks published configuration or route sentinels,
driver environment declarations, registrations in config/commerce.ts,
commerce migrations, and publication baselines. It never modifies the host.
node ace commerce:setup
node ace commerce:setup --json
node ace commerce:doctor --json
node ace commerce:upgrade --check
node ace commerce:upgrade --json
node ace commerce:upgrade --yes--json writes one command report for CI. Application and database debug logs
remain controlled by the host’s logging configuration. Diagnostic commands use
exit code 0 when clean, 1 when action is required, and 2 for invalid
command usage or an unreadable host manifest.
commerce:upgrade --check and commerce:upgrade --json inspect without
prompting or writing. --yes applies every offered publication and migration.
Do not combine --check with --yes. A staged three-way publication conflict
still exits with 1 in --check, --json, or --yes automation modes.
Maintenance
Run one scheduled maintenance implementation immediately:
node ace commerce:maintenance reservations
node ace commerce:maintenance carts
node ace commerce:maintenance checkouts
node ace commerce:maintenance outboxThe four tasks invoke the same ExpireStaleReservations,
ExpireAbandonedCarts, ReconcileStuckCheckouts, and DrainEventOutbox
classes used by the scheduler. They are not dry runs. Add --json for a
machine-readable affected count or outbox delivery result. An outbox result
with failed deliveries exits with 1; an unknown task exits with 2.
Host-owned driver extensions
Publish a functional host-owned extension of a stable driver:
node ace commerce:make:driver payment acme
node ace commerce:make:driver shipping warehouse-rate
node ace commerce:make:driver tax local-tax
node ace commerce:make:driver inventory nearest-warehouseThe command writes a service under app/services/commerce/drivers and prints registration instructions. It supports payment, shipping, tax, inventory, fulfillment, shipping-quote, cart-token, pricing, search, image-storage, shipping-eligibility, tax-address, order-number, and job-dispatcher. The first four delegate to built-in behavior; payment uses the manual provider until you wire the intended gateway. Additional typed factories require an explicit working delegate. Register job-dispatcher adapters in a host provider’s boot hook after commerce, through JobDispatcherService.use(). See all ports and registration details.
Scheduled jobs
Adocommerce Kit schedules these jobs when the service provider starts:
| Job name | Default schedule | Purpose |
|---|---|---|
commerce.expire_pending_payments |
Every minute | Revalidate deferred payments and expire unpaid intents |
commerce.expire_stale_reservations |
Every 5 minutes | Release expired inventory reservations |
commerce.expire_abandoned_carts |
Hourly | Mark inactive carts abandoned and emit the event |
commerce.reconcile_stuck_checkouts |
Every 5 minutes | Recover checkouts older than the reservation threshold |
commerce.reconcile_payment_operations |
Every 5 minutes | Reconcile durable external payment operation claims |
commerce.drain_event_outbox |
Every minute | Deliver pending transactional outbox events |
commerce.purge_expired_idempotency_keys |
Daily | Delete expired idempotency records |
The default inline dispatcher creates timers inside the Adonis process. It is appropriate for development and a single long-lived process. It is a poor default for horizontal scaling, serverless instances, or frequently recycled processes because every process schedules its own copy and timers disappear when the process stops.
For a multi-instance deployment:
// config/commerce.ts
jobs: { dispatcher: 'queue' },Install and configure the compatible @adonisjs/queue peer dependency and run its workers according to that package’s deployment model. The queue adapter is experimental while the upstream package remains pre-1.0, so cover it in release tests.
Monitor job age, failures, and duration. In particular, alert when stale reservations, stuck checkouts, or outbox rows continue growing beyond more than one schedule interval.
The maintenance CLI exposes only reservations, carts, checkouts, and outbox. Payment expiry,
payment-operation reconciliation, and idempotency cleanup run through their registered jobs;
do not invent commerce:maintenance task names for them. Pending capture/refund rows and
started/uncertain payment operations must be reconciled against provider state before
another attempt. Use the authorized admin payment-operations reconciliation workflow when
automatic reconciliation cannot establish the result.
With promotions installed, its provider also schedules commerce:promotions:expire-pending every five minutes to release expired pending redemptions. Keep this job running even when no storefront promotion management UI is used.
Transactional event outbox
Enable the outbox when event delivery must survive a process crash after the business transaction commits:
events: {
outbox: {
enabled: true,
drainBatchSize: 100,
},
},The drain job runs every minute. Set a batch size your event handlers and database can process within that interval. Event handlers must remain idempotent because at-least-once delivery can repeat work after partial failures.
Keep the outbox disabled if no durable integration consumes it; enabling storage without monitoring the drain only creates an unbounded operational queue.
Inspect failed outbox records with EventOutboxService.deadLetters({ cursor, limit }); it returns { items, nextCursor }. Pass the opaque next cursor back unchanged: ordering is UUID ID descending, not creation-time ordering. replay(id, options) resets a failed row to pending and returns whether a row was reset; optional trx participates in a host transaction.
Outbound destination administration
Enable the outbox before creating or activating a destination. Secrets and custom headers are encrypted; await toAdminDestination() for the masked destination DTO and use toAdminDelivery() for the minimal delivery DTO. Neither is a raw payload/credential export. Omitted update headers preserve values, null clears them, and an object replaces them. rotateSecret() returns { secret } once: store it securely, because subsequent reads are masked. ping() sends a real test delivery and refuses inactive destinations; replayDelivery() refuses inactive destinations and only accepts failed/dead-lettered deliveries.
listDeliveries({ destinationId, status, cursor, limit }) returns { items, nextCursor } using opaque UUID-descending pagination. Destination mutations, secret rotation, ping, and delivery replay accept mutation transaction options. Review outbound network, timeout, and header safeguards before exposing management actions.
HTTP scaling and rate limits
The generated storefront applies fixed-window limits:
- 120 cart mutations per minute;
- 10 checkout attempts per minute;
- 60 order reads per minute.
Cart mutation and checkout scopes use the configured cart credential when present, falling
back to client IP; order-read scopes use client IP. The default MemoryRateLimitStore
stores bounded counters in one process. For multiple instances, bind a RateLimitStore
under the exported STOREFRONT_RATE_LIMIT_STORE container key. The published middleware
uses that binding without replacement. RedisRateLimitStore is supplied for Redis clients
with the standard eval(script, numberOfKeys, ...args) signature; hosts may provide another
atomic shared store implementing consume().
Configure Adonis proxy trust correctly before relying on client IP. An attacker must not be able to choose the forwarded address used as the rate-limit key.
Payment webhooks
The generated endpoint is:
POST /api/commerce/webhooks/payments/:providerOperational requirements:
- preserve the raw request bytes through the proxy and Adonis middleware chain;
- exclude only the webhook path from browser CSRF checks;
- verify the provider signature before normalization;
- keep provider secrets in the deployment secret store;
- alert on signature failures and repeated handler errors;
- retain enough request correlation metadata to trace a provider event to its payment intent and order.
Verified duplicate and unhandled events return 200 by design. A 200 therefore means the delivery was accepted, not necessarily that it changed a payment. Inspect stored webhook-event state when reconciling provider and application records.
See Stripe payments for provider-specific setup.
Database and backups
Adocommerce Kit stores financial amounts as integer minor units and copies cart state into order snapshots. Treat order, payment, refund, inventory, idempotency, webhook, and outbox tables as application records covered by the same backup and retention policy as the host user data.
At minimum:
- run automated backups and test restoration;
- use one release task for migrations rather than every web instance;
- observe database lock waits during checkout and inventory contention;
- retain completed order and payment records according to legal and accounting requirements;
- anonymize customer PII through the domain service rather than deleting financial history ad hoc.
CustomerService.anonymize(customerId) clears customer/address PII, cart addresses,
linked order emails/address snapshots and metadata, saved payment identities, and stored
provider payloads while preserving financial rows. Order address redaction retains country
codes for tax reporting. Migration 019_customer_privacy adds the anonymizedAt marker.
This is not an automatic core retention schedule: retention windows and legal holds belong
to the host or the optional Indonesia PDP integration.
Changing tablePrefix after migration requires a deliberate host migration. The configuration change alone points Adocommerce Kit at new table names.
Logs, metrics, and alerts
Adocommerce Kit uses structured exceptions but does not install a monitoring backend. The host should record the commerce error code, request or job correlation ID, cart/order/payment identifiers, and provider event ID without logging card data, payment tokens, secrets, or full addresses.
Useful counters and alerts:
- checkout success, conflict, price-change, stock, and payment-decline rates;
- checkout latency and database lock time;
- reservation expiration and stuck-checkout reconciliation counts;
- webhook signature failures, duplicates, unhandled types, and processing failures;
- outbox backlog age and drain failures;
- payment authorization-to-capture and refund failures;
- pending-payment expiry, under/overpayment, conflicting provider status, and paid-after-expiry review counts;
- dynamic quote rejection and fulfillment return/restock failures;
commerce:doctorrelease failures.
Upgrade procedure
Generated files use a recorded publication baseline. Upgrade in a development branch, never directly on a production host. Official packages use lockstep versions, so raise every installed package in one command rather than a subset:
pnpm up --save-exact @adocommercekit/core@<version> \
@adocommercekit/promotions@<version> \
@adocommercekit/preorders@<version> \
@adocommercekit/store-credit@<version> \
@adocommercekit/engagement@<version> \
@adocommercekit/storefront-api@<version> \
@adocommercekit/admin-api@<version> \
@adocommercekit/admin@<version> \
@adocommercekit/stripe@<version> \
@adocommercekit/midtrans@<version> \
@adocommercekit/xendit@<version> \
@adocommercekit/id@<version> \
@adocommercekit/biteship@<version> \
@adocommercekit/rajaongkir@<version> \
@adocommercekit/whatsapp@<version>
node ace commerce:upgradeDrop the lines for packages the host does not install. Never mix official package versions in a production pilot.
Then:
- Read package release notes and the stability policy.
- Review new migration stubs and every generated-file diff.
- Resolve files staged under
.commercekit/incoming; the command does not overwrite host changes. - Keep
.commercekit/publicationsupdated and committed. - Run application typecheck, tests, and a complete checkout smoke.
- Back up the database and use the normal deployment sequence.
commerce:upgrade --yes accepts safe add/update actions non-interactively, but it still does not resolve conflicts. Do not use it as a substitute for reviewing host-owned code.
The report distinguishes noop (stock-equivalent, baseline healed during apply), kept (retain host customization), removed-by-host (preserve deletion), unconfigured (no recorded publication ownership), and error as well as add/update/conflict. New publications are discovered only within a package already represented by a baseline; installation alone does not authorize publishing files. Hash comparison only normalizes leading BOM, CRLF, and trailing newlines. Resolve loader/read errors before deployment. Advisory IDs and summaries accompany affected artifacts. A security advisory fails automated check status while its fix is unapplied: an unmerged conflict, or a pending update under --check. A kept copy has already been merged against the current stock source, so its advisory is reported but does not fail the check.
Optional upgrade loaders include storefront API, admin API/panel, Indonesia, promotions, preorders, store credit, engagement, WhatsApp, and Biteship. After manual merging, the publication base must contain incoming stock source, never the resolved customized host output. Keep host customizations outside that baseline.
Panel extensions (Indonesia, promotions) are offered by commerce:upgrade only after the extension was configured against a published panel, because the extension’s panel controllers render its pages. If you install @adocommercekit/admin after such a package, re-run node ace configure @adocommercekit/<package> once to publish its pages, controllers, and registration together.
Current core and domain migrations
The ordered exported coreMigrations registry now includes 015_returns, 016_operational_depth, 017_payment_reconciliation, 018_inventory_backorders, 019_customer_privacy, and 020_webhook_hardening. Review each missing migration offered by upgrade and run node ace migration:run after publication. Migration 017 backfills legacy captures/refund associations and preserves the backfilled money ledger on rollback. Migration 020 encrypts existing destination headers and removes plaintext storage; migrate custom destination models to nonserialized headersEnc and retain encryption keys.
The complete ordered stub chain is:
| Range | Migrations |
|---|---|
| 001–005 | foundation, catalog, customers, pricing, fulfillment_taxes |
| 006–010 | carts, orders_inventory, payments_infrastructure, transaction_beta, generic_seams |
| 011–015 | admin_seams, product_images, durability_hardening, external_events, returns |
| 016–020 | operational_depth, payment_reconciliation, inventory_backorders, customer_privacy, webhook_hardening |
Migration 018 adds reservations.backordered_quantity and its FIFO lookup index;
consumption preserves nonnegative on-hand stock and later receipts satisfy outstanding
backorders. Migration 019 adds customers.anonymized_at; deploy it before invoking the
updated anonymization service.
Promotions’ ./upgrade loader tracks validators, storefront and management controllers/routes, the existing-schema promotion_kinds migration, and conditional panel pages/navigation/catalog files. Admin API publications require its host service to have been published; panel publications require the panel host. Review the offered artifacts, configure the intended surfaces when not yet owned, and migrate before using new campaign kinds.
Existing preorder hosts receive the additive preorder_deposits migration through commerce:upgrade or node ace configure @adocommercekit/preorders, followed by node ace migration:run. Fresh preorder schema already includes deposit fields. Legacy allocations remain fully paid with zero outstanding balance.
Upgrade to 1.1.0
Migration 010_generic_seams is additive on populated SQLite, PostgreSQL, and MySQL databases. It adds nullable/defaulted parcel, quote, deferred-payment, webhook-status, fulfillment, and metadata columns plus the payment_instructions table. Run it before enabling a deferred, COD, quote, or fulfillment provider.
commerce:upgrade also proposes the 14th storefront route, the payment-instruction controller action, checkout quote-token validation, and transformer hydration. The instruction route must keep the same guest-token/authenticated-customer ownership check as the order route.
An upgraded host with its existing payment methods and static shipping configuration remains on the authorize/capture path. Enabling a deferred provider in production additionally requires jobs.dispatcher: 'queue'; verify this with node ace commerce:doctor.
Rollback the application before enabling a new seam. The previous application ignores migration 010’s additive fields and table, so the schema may remain in place for a forward fix. Do not run migration down() in production after instructions, quote selections, or fulfillment data have been written; doing so discards those records and columns.
Upgrade regional packages
The Indonesia packages build on the generic deferred-payment, shipping, fulfillment, and jobs seams without changing an unmodified host’s behavior. Each regional package publishes its own migrations or host-owned integration files. @adocommercekit/id adds the kode-unik lease table and the Indonesian regional, PDP, and COD tables, plus config, validator, controller, and route stubs tracked through @adocommercekit/id/upgrade.
Before enabling any regional provider in production:
- configure a durable queue and set
jobs.dispatcher: 'queue'; deferred payments, COD, and WhatsApp retries all depend on it; - import a licensed region source with
commerce:id:regions-import, because no region rows are bundled; - pin each provider’s API version and revalidate it against the live provider contract;
- confirm webhook verification is configured; Biteship tracking and WhatsApp fail closed without a host verifier;
- run
node ace commerce:doctorso driver credential pings and the deferred-payment queue requirement are checked.
Use Build commerce for Indonesia for the complete capability map and the PDP operations runbook for consent, rights, retention, and incident duties.
Rollback
Application rollback is safe only when the previous application version can read the migrated schema. Before applying a migration, determine whether it is backward compatible with the currently running version.
If it is not:
- stop the rollout before mixed versions serve traffic;
- take a verified backup;
- deploy application and schema in an explicitly coordinated window;
- restore from backup or apply a reviewed forward fix if rollback is required.
Do not edit or delete already-applied Adocommerce Kit migration files to force a rollback. Add host migrations that express the intended change and preserve the migration history.
Contributor and release gates
The release train is derived from nonprivate package manifests, including create-adocommerce, @adocommercekit/store-credit, and @adocommercekit/engagement, rather than a fixed package list. Tagged releases first run scripts/check_release_tag.mjs: v<version> must match every train manifest before publication.
CI uses Node.js 24 and pnpm 10.13.1 with a frozen lockfile. Bootstrap playground and example hosts from .env.example, generate ephemeral app keys, and create their tmp directories before host tests. Browser suites require Playwright Chromium and its system dependencies (pnpm --filter playground exec playwright install --with-deps chromium). SQL functional CI covers SQLite, PostgreSQL 14, and MySQL 8.
pnpm lint includes migration SQL-identifier guards, Lucid DateTime query-update guards, and stub-template guards. Scaffolder pack checks exercise the built binary’s help and deterministic dry-run plans for every starter kit, including empty extras and monorepo layout. Upstream starter-layout network tests are opt-in with ADOCOMMERCEKIT_NETWORK_SMOKE=1; ordinary offline tests do not establish upstream availability.
Tagged publication also requires the protected S4_ID30_EVIDENCE and S4_ID31_EVIDENCE
secrets. The workflow materializes them as restricted JSON files, runs pnpm s4:release,
then publishes through Changesets. The ordinary CI workflow additionally runs a
three-dialect upgrade-compatibility matrix and a pack/install job after quality and
functional gates.