@adocommercekit/preorders is an optional package for scheduled preorder sales, allocation
limits, storefront availability, deposits, and release workflows. Its cart processor reserves
preorder capacity transactionally, while its backorder policy admits active preorder variants
through the core inventory workflow.
Install and configure
Configure core, @adocommercekit/storefront-api, and @adocommercekit/admin-api first, using the
same exact lockstep version for every commerce package:
pnpm add @adocommercekit/preorders
node ace configure @adocommercekit/preorders
node ace migration:runThe configurator registers @adocommercekit/preorders/preorders_provider and publishes:
config/commerce_preorders.tsandapp/validators/commerce_preorders.ts;- timestamped preorders and preorder-deposits migrations using core’s table prefix;
- storefront and admin preorder controllers under
app/controllers/commerce/andapp/controllers/commerce_admin/; start/routes/commerce_preorders.ts, registered as a preload;- publication baselines under
.commercekit/publications.
The HTTP files are published unconditionally and use middleware and services from both API packages. A service-only application must adapt or remove the host-owned routes.
The provider registers PreorderService, the cart processor, the inventory backorder policy,
checkout validation and allocation steps, and the core capture-amount resolver used for placement
and stuck-checkout recovery. It subscribes to OrderCanceled to release allocations and to
PaymentCaptured to record deposit capture; keep both subscriptions active.
Preorder states
PreorderService manages draft, scheduled, active, paused, released, and cancelled
preorders. Allocations move through pending, ready, fulfilled, and cancelled;
fulfillment is a separate allocation transition from release.
Payment and allocation lifecycle
Set either depositPercent (0.01–100, at most two decimal places) or depositAmount
(positive safe integer in minor units), never both. Neither means full payment.
A fixed deposit is capped at the allocation value; percentage deposits round up to a minor unit.
Placement authorizes the order amount and captures non-preorder amounts plus preorder deposits,
leaving allocation balances outstanding. Allocations track depositAmount, balanceAmount,
depositState (pending, captured, refunded), and balanceState (pending, captured).
Releasing a campaign captures pending balances before changing allocations to ready;
an unsuccessful balance capture prevents release.
Deposit checkout requires a provider supporting both authorize and capture. Confirm that its
authorization validity window and partial/multiple-capture behavior cover the preorder schedule:
a deposit does not extend provider authorization lifetime. PreorderService accepts
PreorderOptions with clock and payments; the cart processor also accepts a clock option.
refundDepositOnCancel defaults to true. Canceling an unfulfilled allocation refunds its
captured deposit using a capture-specific idempotent refund before releasing capacity;
an incomplete refund prevents completion. OrderCanceled releases pending/ready allocations.
Fulfilled allocations cannot be canceled, and fulfilled returns do not reopen campaign capacity.
See money and ledgers for how deposits interact with order value.
Cart and checkout behavior
Paused, ended/expired, sold-out, over-limit, or over-capacity lines remain editable in the cart.
Their zero-value preorder adjustment is ineligible and carries metadata.reason and
metadata.errorCode; checkout rejects the affected line with E_PREORDER_NOT_AVAILABLE
or E_PREORDER_LIMIT. Remove or change the line rather than treating cart acceptance as
a checkout guarantee.
Routes and abilities
Storefront availability is GET /api/commerce/variants/:variantId/preorder
(commerce.preorders.show), rate limited to 120 requests per minute.
Admin management mounts under /api/commerce/admin:
| Method | Path | Ability |
|---|---|---|
GET |
/preorders |
commerce.products.view |
POST |
/preorders |
commerce.products.manage |
PATCH |
/preorders/:id |
commerce.products.manage |
POST |
/preorders/:id/activate |
commerce.products.manage |
POST |
/preorders/:id/pause |
commerce.products.manage |
POST |
/preorders/:id/release |
commerce.products.manage |
POST |
/preorders/:id/cancel |
commerce.products.manage |
GET |
/preorders/:id/allocations |
commerce.products.view |
POST |
/preorder-allocations/:allocationId/fulfill |
commerce.products.manage |
POST |
/preorder-allocations/:allocationId/cancel |
commerce.products.manage |
Preorders reuse the product abilities rather than adding new ones. Route names are listed in the admin REST reference.
Public entrypoints
| Import | Contents |
|---|---|
@adocommercekit/preorders |
Config helper, exception, models, service, cart/backorder integrations, availability resolver |
@adocommercekit/preorders/models |
Preorder, PreorderAllocation, and their status types |
@adocommercekit/preorders/services |
PreorderService, cart processor, backorder policy, availability resolver, and types |
@adocommercekit/preorders/configure |
Adonis configure hook |
@adocommercekit/preorders/preorders_provider |
Adonis service provider |
@adocommercekit/preorders/upgrade |
Manifest and publication artifact loader for upgrades |
Upgrade published files
For existing hosts, commerce:upgrade or reconfiguration publishes the additive
preorder_deposits migration; run node ace migration:run. Fresh schema already contains
deposit fields. Legacy allocations remain fully paid with zero outstanding balance.