Skip to content

Preorders

Sell scheduled preorders with allocation limits, deposits, release capture, and cancellation refunds.

@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:run

The configurator registers @adocommercekit/preorders/preorders_provider and publishes:

  • config/commerce_preorders.ts and app/validators/commerce_preorders.ts;
  • timestamped preorders and preorder-deposits migrations using core’s table prefix;
  • storefront and admin preorder controllers under app/controllers/commerce/ and app/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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close