@86d-app/preorders

The Modern Foundation for Commerce

X · LinkedIn

This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

Preorders Module

Documentation: 86d.app/docs/modules/preorders

Preorder campaign management for upcoming, limited-edition, or out-of-stock products. Create time-bound campaigns with full payment or deposit options, track customer preorders through the fulfillment lifecycle, and notify customers when products are ready to ship.

Installation

npm install @86d-app/preorders

Usage

import preorders from "@86d-app/preorders";

const module = preorders({
  defaultMessage: "Expected to ship Q2 2027",
});

Configuration

Option	Type	Default	Description
defaultMessage	string	—	Default message shown on preorder campaign pages

Store Endpoints

Method	Path	Description
GET	/preorders/campaigns	List active preorder campaigns (filterable by productId)
GET	/preorders/campaigns/:id	Get an active campaign's details
GET	/preorders/check/:productId	Check if a product has an active preorder campaign
POST	/preorders/place	Place a preorder for a campaign
GET	/preorders/mine	List the current customer's preorders
POST	/preorders/:id/cancel	Cancel a preorder

Admin Endpoints

Method	Path	Description
GET	/admin/preorders/campaigns	List all campaigns (filterable by status, productId)
POST	/admin/preorders/campaigns/create	Create a new preorder campaign
GET	/admin/preorders/campaigns/:id	Get campaign details with preorder items
PATCH	/admin/preorders/campaigns/:id/update	Update campaign fields
POST	/admin/preorders/campaigns/:id/activate	Activate a draft or paused campaign
POST	/admin/preorders/campaigns/:id/pause	Pause an active campaign
POST	/admin/preorders/campaigns/:id/complete	Mark campaign as completed
POST	/admin/preorders/campaigns/:id/cancel	Cancel campaign and all pending items
POST	/admin/preorders/campaigns/:id/notify	Notify confirmed/ready customers
GET	/admin/preorders/items	List all preorder items (filterable)
POST	/admin/preorders/items/:id/fulfill	Fulfill a preorder item
POST	/admin/preorders/items/:id/ready	Mark a preorder item as ready to ship
POST	/admin/preorders/items/:id/cancel	Cancel a preorder item
GET	/admin/preorders/summary	Dashboard summary with campaign and revenue stats

Admin UI

The module includes admin UI components in src/admin/components/index.tsx (client components using useModuleClient):

Page	Component	Description
/admin/preorders	CampaignList	Campaign list with status filters, create forms, and lifecycle actions
/admin/preorders/campaigns/:id	CampaignDetail	Campaign detail with preorder items, fulfillment, and customer notifications

Controller API

interface PreordersController {
  createCampaign(params: {
    productId: string;
    productName: string;
    variantId?: string;
    variantLabel?: string;
    paymentType: "full" | "deposit";
    depositAmount?: number;
    depositPercent?: number;
    price: number;
    maxQuantity?: number;
    startDate: Date;
    endDate?: Date;
    estimatedShipDate?: Date;
    message?: string;
  }): Promise<PreorderCampaign>;

  getCampaign(id: string): Promise<PreorderCampaign | null>;
  listCampaigns(params?: { status?; productId?; take?; skip? }): Promise<PreorderCampaign[]>;
  updateCampaign(id: string, updates: { productName?; paymentType?; depositAmount?; depositPercent?; price?; maxQuantity?; endDate?; estimatedShipDate?; message? }): Promise<PreorderCampaign | null>;
  activateCampaign(id: string): Promise<PreorderCampaign | null>;
  pauseCampaign(id: string): Promise<PreorderCampaign | null>;
  completeCampaign(id: string): Promise<PreorderCampaign | null>;
  cancelCampaign(id: string, reason?: string): Promise<PreorderCampaign | null>;

  placePreorder(params: { campaignId; customerId; customerEmail; quantity }): Promise<PreorderItem | null>;
  getPreorderItem(id: string): Promise<PreorderItem | null>;
  listPreorderItems(params?: { campaignId?; customerId?; status?; take?; skip? }): Promise<PreorderItem[]>;
  getCustomerPreorders(customerId: string, params?: { take?; skip? }): Promise<PreorderItem[]>;
  cancelPreorderItem(id: string, reason?: string): Promise<PreorderItem | null>;
  fulfillPreorderItem(id: string, orderId?: string): Promise<PreorderItem | null>;
  markReady(id: string): Promise<PreorderItem | null>;
  notifyCustomers(campaignId: string): Promise<{ notified: number; itemIds: string[] }>;
  getSummary(): Promise<PreorderSummary>;
  getActiveCampaignForProduct(productId: string, variantId?: string): Promise<PreorderCampaign | null>;
}

Types

type CampaignStatus = "draft" | "active" | "paused" | "completed" | "cancelled";
type PreorderItemStatus = "pending" | "confirmed" | "ready" | "fulfilled" | "cancelled" | "refunded";
type PaymentType = "full" | "deposit";

interface PreorderCampaign {
  id: string;
  productId: string;
  productName: string;
  variantId?: string;
  variantLabel?: string;
  status: CampaignStatus;
  paymentType: PaymentType;
  depositAmount?: number;
  depositPercent?: number;
  price: number;
  maxQuantity?: number;
  currentQuantity: number;
  startDate: Date;
  endDate?: Date;
  estimatedShipDate?: Date;
  message?: string;
  createdAt: Date;
  updatedAt: Date;
}

interface PreorderItem {
  id: string;
  campaignId: string;
  customerId: string;
  customerEmail: string;
  quantity: number;
  status: PreorderItemStatus;
  depositPaid: number;
  totalPrice: number;
  orderId?: string;
  notifiedAt?: Date;
  cancelledAt?: Date;
  cancelReason?: string;
  fulfilledAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

interface PreorderSummary {
  totalCampaigns: number;
  activeCampaigns: number;
  totalItems: number;
  pendingItems: number;
  confirmedItems: number;
  fulfilledItems: number;
  cancelledItems: number;
  totalRevenue: number;
  totalDeposits: number;
}

Campaign Lifecycle

draft → active ⇄ paused → completed
   ↘       ↘        ↘
              cancelled

• draft: Campaign created with a future start date, not yet accepting preorders
• active: Campaign is live and accepting preorders
• paused: Temporarily stopped accepting new preorders
• completed: All preorders fulfilled, campaign finished
• cancelled: Campaign terminated, all pending/confirmed items auto-cancelled

Item Lifecycle

pending → confirmed → ready → fulfilled
   ↘         ↘
       cancelled / refunded

• pending: Customer placed preorder, awaiting confirmation
• confirmed: Payment verified, preorder confirmed
• ready: Product is available and ready to ship
• fulfilled: Order shipped to customer
• cancelled: Preorder was cancelled before fulfillment
• refunded: Payment was refunded after cancellation

Store Components

Component	Description
PreorderButton	Button to place a preorder for a product with an active campaign
MyPreorders	List of the current customer's preorders with status tracking

Usage

import { PreorderButton, MyPreorders } from "@86d-app/preorders/store/components";

<PreorderButton productId="abc-123" />
<MyPreorders customerId="customer-456" />

Notes

• Campaigns auto-activate when startDate is in the past at creation time.
• For deposit-based campaigns, depositAmount takes precedence over depositPercent. If neither is set, full price is charged.
• Cancelling a campaign automatically cancels all pending and confirmed preorder items with the reason "Campaign cancelled".
• currentQuantity is automatically incremented on preorder placement and decremented on cancellation.
• The notifyCustomers endpoint marks confirmed/ready items as notified (idempotent — skips already-notified items).
• The module requires the products module.