Adocommerce Kit has fifteen runtime packages plus the create-adocommerce scaffolder. The
workspace manifests currently use the lockstep 1.3.0-0 prerelease version; every public package
publishes together. Install matching exact versions and review
stability and compatibility before deployment.
Package catalog
| Package | Tier | Purpose |
|---|---|---|
create-adocommerce |
Beta | Project scaffolder with compatible package selection |
@adocommercekit/core |
Beta | Commerce domains, models, migrations, workflows, events, jobs, and commands |
@adocommercekit/promotions |
Beta | Campaigns, rules, coupons, usage limits, and cart discounts |
@adocommercekit/preorders |
Beta | Scheduled preorders, allocation limits, deposits, and release |
@adocommercekit/store-credit |
Beta | Gift cards and store credit as checkout tender |
@adocommercekit/engagement |
Beta | Wishlists and verified-purchase reviews |
@adocommercekit/storefront-api |
Beta | Host-owned REST storefront under /api/commerce |
@adocommercekit/admin-api |
Beta | Host-owned REST management surface with audit trail |
@adocommercekit/admin |
Experimental | Inertia + React management panel at /admin/commerce |
@adocommercekit/stripe |
Beta | Stripe PaymentIntents payment driver |
@adocommercekit/midtrans |
Beta | Midtrans QRIS, virtual accounts, GoPay, and retail channels |
@adocommercekit/xendit |
Beta | Xendit QRIS, virtual accounts, and e-wallet redirects |
@adocommercekit/id |
Beta | Kode unik, regions, addresses, PPN, COD remittance, and UU PDP |
@adocommercekit/biteship |
Beta | Biteship rates, waybills, tracking, insurance, and COD |
@adocommercekit/rajaongkir |
Experimental | RajaOngkir rates and available tracking |
@adocommercekit/whatsapp |
Experimental | Consent-aware WhatsApp template notifications |
Choosing a package set
| Application shape | Install |
|---|---|
| Custom controllers, jobs, or GraphQL API | @adocommercekit/core |
| Headless REST storefront | @adocommercekit/core and @adocommercekit/storefront-api |
| Stripe payments with custom HTTP surface | @adocommercekit/core and @adocommercekit/stripe |
| Campaigns, coupons, and cart discounts | Core plus @adocommercekit/promotions |
| Scheduled preorder sales | Core plus @adocommercekit/preorders |
| Gift-card/store-credit checkout tender | Core plus @adocommercekit/store-credit |
| Wishlists and verified-purchase reviews | Core plus @adocommercekit/engagement |
| Headless management API | Core plus @adocommercekit/admin-api and its Bouncer peer |
| Inertia + React management panel | Core, admin API, @adocommercekit/admin, and its host UI dependencies |
| Indonesian gateway payments | Core plus @adocommercekit/midtrans or @adocommercekit/xendit |
| Kode-unik manual transfer | Core plus @adocommercekit/id |
| Indonesian REST storefront payments | Core, storefront API, and the selected regional payment package(s) |
| Indonesian logistics quotes | Core, ID, and @adocommercekit/biteship or @adocommercekit/rajaongkir |
| Biteship waybill and tracking | Core, ID, and @adocommercekit/biteship |
| Consent-aware WhatsApp updates | Core, ID, and @adocommercekit/whatsapp |
create-adocommerce
The recommended new-project entrypoint delegates to the official AdonisJS generator, selects compatible commerce packages, installs their shared lockstep version, and invokes their existing configurators:
pnpm create adocommerce@latest my-storeIt also supports complete non-interactive invocations through --yes; run the command with
--help for package keys, database selection, migration control, and dry-run planning. Existing
applications should continue to install and configure the runtime packages directly.
Starter kits are hypermedia, react, vue, api, and api-monorepo; only the last
targets apps/backend instead of the project root. The admin selection requires React
and adds admin-api; whatsapp adds id. Optional keys include store-credit and
engagement; --packages= or --packages=none selects core alone.
--resume requires an existing ace.js, skips upstream creation, and repeats the selected
installation/configuration plan rather than tracking completed operations. See
the scaffold workflow for defaults and host steps.
@adocommercekit/core
The core package owns the domain contract and Adonis integration. It includes:
- twenty host-owned migrations for channels, catalog and product images, customers, pricing, carts, fulfillment, taxes, orders, returns, inventory/backorders, deferred/COD payments, payment instructions and reconciliation, customer privacy, encrypted webhook headers, idempotency, event outbox, and workflow state;
- Lucid models, product/variant image relationships, and a runtime model registry;
- catalog, product-image, media-library, customer, pricing, cart, shipping, fulfillment, tax, inventory, order, return, payment, checkout, search, idempotency, event-outbox, outbound-webhook, external-event-inbox, and admin-metrics services;
- money, parcel, capability, state-machine, workflow, event, transformer, job, search-driver, storage-driver, and error primitives;
- the Commerce service provider and Ace commands.
Install and configure it first:
pnpm add @adocommercekit/core
node ace configure @adocommercekit/core
node ace migration:run
node ace commerce:doctorPublic entrypoints
| Import | Contents |
|---|---|
@adocommercekit/core |
Configuration, money, errors, CommerceManager, state machines, and workflows |
@adocommercekit/core/commerce_provider |
Adonis service provider; normally registered by the configurator |
@adocommercekit/core/configure |
Adonis configure hook |
@adocommercekit/core/commands |
Ace command entrypoint; normally registered by the configurator |
@adocommercekit/core/services/main |
Domain services and checkout workflow |
@adocommercekit/core/models |
Lucid models and model-registry APIs |
@adocommercekit/core/events |
Typed domain events and transactional emitter |
@adocommercekit/core/drivers |
Built-in drivers and driver interfaces |
@adocommercekit/core/transformers |
Storefront-safe transformers |
@adocommercekit/core/types |
Shared domain and port types |
@adocommercekit/core/validators |
Exported VineJS validators |
@adocommercekit/core/errors |
Commerce exceptions and HTTP status mapping |
@adocommercekit/core/jobs |
Maintenance job classes and stable job names |
@adocommercekit/core/policies |
Admin policy catalog, role resolution, and ability types |
@adocommercekit/core/testing |
Deterministic fake synchronous and deferred providers for host tests |
@adocommercekit/core/upgrade |
Publication upgrade planning APIs |
@adocommercekit/core/extension |
Published package-extension contracts and fragment helpers |
Prefer these documented entrypoints. Files below them are package internals and are not part of the published export map.
Inventory, backorders, and return restocking
Reservation increases reserved, including quantities admitted by a preorder/backorder policy.
Consumption removes available physical stock, writes sale movements only for that stock, and
stores the unmet portion in Reservation.backorderedQuantity; it does not make onHand negative.
InventoryService.receive() writes the receipt, then commits outstanding consumed backorders
FIFO by reservation createdAt and id, writing sale movements and reducing their backordered
quantities before leaving the remaining stock available.
restockFromReturn(input: { variantId: string; quantity: number; reference: string; locationId?: string }, options?: MutationOptions): Promise<InventoryMovement | null> writes a positive return movement.
Quantity must be a positive integer. Omitting locationId selects the default stock location
(lowest ID if more than one exists), and a missing default raises a not-found error.
Missing or untracked inventory items return null rather than creating stock.
See events and returns and fulfillment.
Commerce feature packages
Feature packages add services and host-owned publications on top of core. Each has a dedicated guide with configuration, lifecycle rules, routes, abilities, and entrypoints.
@adocommercekit/promotions
This optional package adds promotion campaigns, eligibility rules, coupon codes, transactional usage claims, per-campaign and per-customer limits, deterministic stacking, and line-level cart discount adjustments.
pnpm add @adocommercekit/promotions
node ace configure @adocommercekit/promotions
node ace migration:runThe published coupon routes require a configured storefront API; management routes and panel pages publish only into an already configured admin API or panel. See Promotions and coupons.
@adocommercekit/preorders
This optional package adds scheduled preorder sales, allocation limits, storefront availability, and release workflows. Its cart processor reserves preorder capacity transactionally, while its backorder policy allows active preorder variants through the core inventory workflow.
pnpm add @adocommercekit/preorders
node ace configure @adocommercekit/preorders
node ace migration:runIts HTTP files use both API packages, so configure @adocommercekit/storefront-api and
@adocommercekit/admin-api first. See Preorders for deposits, release capture,
and cancellation refunds.
@adocommercekit/store-credit
Optional gift-card/store-credit tender, bearer-code issuance, balance holds, captures,
releases, refunds, and an append-only ledger. Configure after core and run its migration.
Storefront and admin controllers/routes are published only when their corresponding API
surface already exists; core-only hosts can use GiftCardService directly.
Entrypoints are @adocommercekit/store-credit (service, processor, configuration, models, errors),
@adocommercekit/store-credit/configure, @adocommercekit/store-credit/gift_cards_provider, and
@adocommercekit/store-credit/upgrade (manifest and root-aware artifact loader).
Use @adocommercekit/store-credit/models and @adocommercekit/store-credit/services for
the dedicated model and service entrypoints.
The 1.3.0-0 prerelease adds this package, one-time issuance codes, safe balance-ledger operations,
and checkout/return tender integration. See Gift cards and store credit
for installation, security, routes, and upgrades.
@adocommercekit/engagement
Optional customer-owned default/named wishlists and delivered-purchase product reviews,
with moderation and approved-only rating aggregates. Configure after core and run its migration.
HTTP publication is optional; core-only hosts use EngagementService without API dependencies.
Entrypoints are @adocommercekit/engagement (service, configuration, errors),
@adocommercekit/engagement/configure, @adocommercekit/engagement/engagement_provider, and
@adocommercekit/engagement/upgrade (manifest and root-aware artifact loader).
Dedicated entrypoints @adocommercekit/engagement/models and
@adocommercekit/engagement/services expose models and service contracts.
See Wishlists and verified reviews for routes, ownership, moderation, and upgrades.
HTTP surfaces
These packages publish editable controllers, routes, and middleware into the host application instead of mounting runtime code from node_modules.
@adocommercekit/storefront-api
This optional package publishes a REST storefront into the host application. It does not mount runtime code from node_modules.
pnpm add @adocommercekit/storefront-api
node ace configure @adocommercekit/storefront-apiThe configurator publishes:
- product, customer-account, cart, checkout, order, return, and payment-webhook controllers;
- request validators and serialization helpers;
- commerce error, fixed-window rate-limit, and raw-body middleware;
- 27 routes below
/api/commerce, including customer portability, return requests, and authorized payment-instruction reads; - upgrade baselines in
.commercekit/publications.
The generated code is intentionally editable. Keep the route names if other application code depends on them, but otherwise treat the files like normal host code.
Public entrypoints
| Import | Contents |
|---|---|
@adocommercekit/storefront-api |
Endpoint contract, configure hook, and fixed-window limiter |
@adocommercekit/storefront-api/configure |
Adonis configure hook |
@adocommercekit/storefront-api/contract |
Storefront prefix and endpoint metadata |
@adocommercekit/storefront-api/upgrade |
Storefront publication artifacts for commerce:upgrade |
See the REST API reference before changing the published contract.
@adocommercekit/admin-api
This optional package publishes a REST management surface and the admin service layer into the host application. It does not mount runtime code from node_modules. Headless hosts stop here; @adocommercekit/admin consumes it.
pnpm add @adocommercekit/admin-api @adonisjs/bouncer
node ace configure @adocommercekit/admin-api
node ace migration:runThe configurator aborts unless @adocommercekit/core is already configured, then publishes:
- one controller group per resource under
app/controllers/commerce_admin/; - request validators and a serialization/idempotency/audit helper service;
- authentication, ability, and actor-keyed rate-limit middleware;
- a deny-by-default Bouncer policy per resource group under
app/policies/commerce/; - 84 routes below
/api/commerce/admin, every one behind an ability from the frozen catalog; - the append-only
admin_audit_entriesmigration; - upgrade baselines in
.commercekit/publications.
Every ability denies until the host implements commerceAdminRoles() in app/policies/commerce/main.ts; commerce:doctor fails while it is unmapped.
Public entrypoints
| Import | Contents |
|---|---|
@adocommercekit/admin-api |
Endpoint contract, ability resolution, rate limiter, shipment transitions, audit service, errors |
@adocommercekit/admin-api/configure |
Adonis configure hook |
@adocommercekit/admin-api/contract |
Admin prefix, endpoint metadata, and rate-limit tiers |
@adocommercekit/admin-api/services |
AdminAuditService and its types |
@adocommercekit/admin-api/admin_provider |
Service provider registering the audit service |
@adocommercekit/admin-api/upgrade |
Admin publication artifacts for commerce:upgrade |
See the Admin REST API reference before changing the published contract.
@adocommercekit/admin
This optional package publishes an Inertia + React management panel into the host application at /admin/commerce. It depends on @adocommercekit/admin-api for its service layer and for the metrics endpoints its charts refetch.
pnpm add @adocommercekit/admin
node ace configure @adocommercekit/adminThe configurator aborts unless @adocommercekit/admin-api and @adonisjs/inertia are configured and every UI runtime dependency is already in the host package.json — it prints the exact pnpm add line and installs nothing. It performs no network access: the coss and Bklit component trees are vendored inside the tarball. It then publishes:
- Inertia controllers under
app/controllers/commerce_admin_panel/, a shared-props/ability/mutation seam, and panel validators; - 69 routes below
/admin/commerce, every one behind an ability from the frozen catalog and the same rate-limit buckets as the REST mutations; - the 17 GET page routes of the closed page inventory under
inertia/pages/admin/commerce/; - 55 vendored coss files and 87 vendored Bklit files under
inertia/components/commerce/, plusregistry_provenance.jsonrecording their upstream revisions, licenses, and content hashes; - money/date/ability/query helpers, the English i18n catalog, and one self-contained Tailwind v4 token layer;
- upgrade baselines in
.commercekit/publications.
The page inventory, the coss primitive set, and the Bklit chart set are closed lists; extending any of them is a specification change. Every panel capability is also reachable through @adocommercekit/admin-api with the same ability and the same audit entry.
Public entrypoints
| Import | Contents |
|---|---|
@adocommercekit/admin |
Panel route contract, host dependency set, publication helpers |
@adocommercekit/admin/configure |
Adonis configure hook |
@adocommercekit/admin/contract |
Panel prefix, route metadata with abilities and page components |
@adocommercekit/admin/upgrade |
Panel publication artifacts, registry provenance, and upgrade report additions |
See the admin panel guide for install, customization, theming, and the vendored-file story.
Payment drivers
@adocommercekit/stripe
This optional package implements the core PaymentProvider port with Stripe PaymentIntents.
pnpm add @adocommercekit/stripe
node ace configure @adocommercekit/stripeThe configure hook adds STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET to the Adonis environment schema. You must still register stripe() in config/commerce.ts.
Public entrypoints
| Import | Contents |
|---|---|
@adocommercekit/stripe |
stripe(), StripePaymentProvider, and StripeOptions |
@adocommercekit/stripe/configure |
Adonis configure hook |
See Stripe setup for registration, checkout, webhook, and local testing instructions.
@adocommercekit/midtrans
Midtrans Core API v2 deferred payments for QRIS, BCA/BNI/BRI virtual accounts, Mandiri bill-key, Permata VA, GoPay, Indomaret, and Alfamart. Configure one factory per checkout method so the selected channel is explicit.
pnpm add @adocommercekit/midtrans
node ace configure @adocommercekit/midtransThe package exports midtrans(), MidtransPaymentProvider, the per-channel MIDTRANS_REFUND_CAPABILITIES matrix, and MidtransManualRefundRequiredError. Automatic refunds are offered only for QRIS and GoPay; other channels require an operator-recorded manual-transfer reference. Notifications use Midtrans’s exact SHA-512 formula, then re-query current transaction status before returning a normalized event.
@adocommercekit/xendit
Xendit Payment Requests API 2024-11-11 deferred payments for QRIS, BCA/BNI/BRI/Mandiri virtual accounts, OVO, and DANA-compatible redirect flows.
pnpm add @adocommercekit/xendit
node ace configure @adocommercekit/xenditThe package exports xendit(), XenditPaymentProvider, and XENDIT_API_VERSION. It uses Basic secret-key API authentication and constant-time x-callback-token webhook verification; Midtrans signature rules do not apply.
Indonesia and logistics
@adocommercekit/id
The Indonesia bundle provides kode-unik payments, an importer-only administrative-region store, opt-in Indonesian address validation and host-published typeahead routes, PMK 131/2024 PPN calculation and audit export, idempotent COD remittance import, UU PDP consent/rights/retention mechanisms, and reviewed-key regional catalogs.
pnpm add @adocommercekit/id
node ace configure @adocommercekit/id
node ace migration:runNo copyrighted region rows are bundled. commerce:id:regions-import --file accepts a host-licensed JSON source with source URL, retrieval date, version, license URL, checksum, corrections, and region records. The configure hook publishes the portable regional/PDP/COD tables plus reviewable host-owned config, validator, controller, and route stubs, records their publication bases, and exposes @adocommercekit/id/upgrade so later commerce:upgrade runs produce reviewable no-op/update/conflict plans. The host must approve the source’s distribution and update terms before import.
kodeUnik() allocates visible codes 001–999 with a normal unique key on (receiving_account, code). ppnCalculator() records the statutory rate, DPP fraction and amount, rounding, price mode, category, and tax in adjustment metadata; PPnBM is not calculated. CustomerService.export() supplies the minimized core portability document, while PdpRightsService adds consent and request receipts behind a mandatory host authorizer. Start with Build commerce for Indonesia and the PDP operations runbook.
@adocommercekit/biteship
Biteship API v1 dynamic rates and fulfillment through the generic quote and fulfillment ports. Full parcel values, weight, dimensions, destination, COD, insurance, currency, and provider options participate in quote/cache identity. Preparation requires the selected courier:service, creates the waybill, and keeps handoff separate.
pnpm add @adocommercekit/biteship
node ace configure @adocommercekit/biteshipThe package exports biteship(), BiteshipProvider, BITESHIP_API_VERSION, and typed failures. Rate cache TTL is capped at 60 seconds. Tracking webhooks fail closed unless the host supplies a verifier matching its pinned Biteship contract.
@adocommercekit/rajaongkir
Komerce RajaOngkir API v1 rates and available tracking provide the second generic quote implementation.
pnpm add @adocommercekit/rajaongkir
node ace configure @adocommercekit/rajaongkirThe package exports rajaOngkir() and RajaOngkirProvider. Its capability declaration explicitly reports waybill creation, fulfillment, COD, and insurance as unsupported rather than emulating them.
@adocommercekit/whatsapp
Opt-in WhatsApp Business Cloud template notifications for order, payment, and shipment events.
pnpm add @adocommercekit/whatsapp
node ace configure @adocommercekit/whatsappThe package requires a caller-pinned Graph API version and current purpose/notice consent both before enqueue and before send. Delivery retries use the jobs port; unapproved templates and retry exhaustion call only a host-configured fallback. Default configuration is disabled and assumes no email or fallback notifier.