Orders

Manage the full order lifecycle in your 86d store. Covers status transitions, fulfillment tracking, returns, invoices, and customer-facing components.

The orders module handles every stage of an order’s life, from the moment it is created through fulfillment, returns, and invoicing. Customers can view their order history, cancel eligible orders, track shipments, and submit return requests directly from your storefront. All store endpoints require an authenticated session, and each endpoint verifies that the order belongs to the requesting customer before returning any data.

Source: modules/orders · npm: @86d-app/orders

Installation

npm install @86d-app/orders

Configuration

import orders from "@86d-app/orders";
import { createModuleClient } from "@86d-app/core";

const client = createModuleClient([
  orders({
    currency: "USD",
  }),
]);

currency · string · default: "\"USD\""

Default currency code applied to new orders. Individual orders can override this when calling controller.create().

Store endpoints

All store endpoints require an authenticated session. Requests for orders that do not belong to the authenticated customer return 404 (not 403), to avoid leaking the existence of other customers’ orders.

Method	Path	Description
GET	/orders/me	List all orders for the authenticated customer
GET	/orders/me/:id	Get a specific order with items and addresses
POST	/orders/me/:id/cancel	Cancel a pending, processing, or on-hold order
GET	/orders/me/:id/fulfillments	List fulfillments and overall fulfillment status
GET	/orders/me/:id/invoice	Get invoice data for an order
GET	/orders/me/:id/returns	List return requests for an order
POST	/orders/me/:id/returns/create	Submit a return request
GET	/orders/me/returns	List all returns across all of the customer’s orders
POST	/orders/me/:id/reorder	Get cart-ready items from a previous order
POST	/orders/track	Guest order tracking (order number + email, no auth required)

POST /orders/me/:id/reorder returns line items ready to be added back to the cart. It does not create a cart or modify any existing cart automatically.

Status flows

Order status:
  pending → processing → on_hold → completed
                                  ↘ cancelled
                                  ↘ refunded

Payment status:
  unpaid → paid → partially_paid → refunded
                ↘ voided

Return status:
  requested → approved → shipped_back → received → refunded → completed
            → rejected

Fulfillment status:
  unfulfilled | partially_fulfilled | fulfilled

An order can only be cancelled when its status is pending, processing, or on_hold. Orders in completed, cancelled, or refunded states cannot be cancelled.

Order numbers are auto-generated in the format ORD-{base36timestamp}-{random}. Invoice numbers follow INV-{YYYYMMDD}-{orderSuffix}.

Events

The module emits the following events that you can subscribe to in other modules or webhooks:

Event	Trigger
order.placed	Order created
order.updated	Order metadata changed
order.fulfilled	Order completed
order.cancelled	Order cancelled
order.shipped	Fulfillment shipped with tracking
shipment.delivered	Fulfillment delivered
return.requested	Return created
return.approved	Return approved
return.rejected	Return rejected
return.refunded	Return refunded
return.completed	Return completed

Components

OrderHistory

Paginated list of a customer’s orders. Requires authentication. Clicking a row triggers the onSelectOrder callback so you can navigate to the order detail view.

<OrderHistory />

Prop	Type	Default	Description
onSelectOrder	(id: string) => void		Callback when a row is clicked
pageSize	number	10	Number of orders per page

OrderDetail

Full order view showing items, totals, fulfillment status, shipping and billing addresses, and a cancel button when the order is eligible for cancellation.

<OrderDetail orderId="ord_abc123" onBack={() => setView("history")} />

Prop	Type	Description
orderId	string	The order ID to display
onBack	() => void	Back navigation callback

OrderReturns

Return requests section for a specific order. Displays existing return requests and exposes a form to submit a new one. Returns are available for orders in completed or processing status.

<OrderReturns
  orderId="ord_abc123"
  items={orderItems}
  orderStatus="completed"
/>

Prop	Type	Description
orderId	string	The order ID
items	OrderItem[]	Order items for return item selection
orderStatus	string	Current order status

OrderTracker

Public order tracking form. No authentication required. Customers enter their order number and the email address used at checkout to retrieve order status.

<OrderTracker />

Types

type OrderStatus =
  | "pending" | "processing" | "on_hold"
  | "completed" | "cancelled" | "refunded";

type PaymentStatus =
  | "unpaid" | "paid" | "partially_paid" | "refunded" | "voided";

type ReturnStatus =
  | "requested" | "approved" | "rejected"
  | "shipped_back" | "received" | "refunded" | "completed";

type ReturnType = "refund" | "exchange" | "store_credit";

type OrderFulfillmentStatus =
  | "unfulfilled" | "partially_fulfilled" | "fulfilled";

interface Order {
  id: string;
  orderNumber: string;        // e.g. "ORD-lq3k7a-x9p"
  customerId?: string;
  guestEmail?: string;
  status: OrderStatus;
  paymentStatus: PaymentStatus;
  subtotal: number;           // in cents
  taxAmount: number;
  shippingAmount: number;
  discountAmount: number;
  total: number;
  currency: string;
  notes?: string;
  metadata: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

interface OrderItem {
  id: string;
  orderId: string;
  productId: string;
  variantId?: string;
  name: string;       // snapshotted at order creation
  sku?: string;
  price: number;      // snapshotted at order creation, in cents
  quantity: number;
  subtotal: number;
  metadata: Record<string, unknown>;
}

interface Fulfillment {
  id: string;
  orderId: string;
  status: OrderFulfillmentStatus;
  trackingNumber?: string;
  trackingUrl?: string;       // auto-generated for UPS, USPS, FedEx, DHL
  carrier?: string;
  notes?: string;
  shippedAt?: Date;
  deliveredAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

interface ReturnRequest {
  id: string;
  orderId: string;
  status: ReturnStatus;
  type: ReturnType;
  reason: string;
  customerNotes?: string;
  adminNotes?: string;
  refundAmount?: number;
  trackingNumber?: string;
  trackingUrl?: string;
  carrier?: string;
  createdAt: Date;
  updatedAt: Date;
}

Item name and price are snapshotted at order creation time. Subsequent changes to the product catalog do not affect existing order records.