Order Lifecycle

This guide covers order statuses, state transitions, admin actions, notifications, and order management throughout the complete lifecycle.

Overview

Orders track two independent status dimensions:

• Order status — Fulfillment lifecycle (PENDING through DELIVERED/CANCELLED/REFUNDED)
• Payment status — Payment state (PENDING through PAID/FAILED/REFUNDED)

Both statuses are stored on the Order model and can be updated independently.

Order Statuses

Defined in lib/validations/orders.ts (mirrors the Prisma OrderStatus enum):

Payment Statuses

Defined in lib/validations/orders.ts (mirrors the Prisma PaymentStatus enum):

Status Flow Diagram

                     +----------+
                     | PENDING  |
                     +----+-----+
                          |
               Payment confirmed
               (checkout/complete or webhook)
                          |
                     +----v-----+
                +--->| CONFIRMED |<---+
                |    +----+-----+    |
                |         |          |
                |    Admin action    |
                |    "Processing"    |
                |         |          |
                |    +----v------+   |
                |    | PROCESSING|   |
                |    +----+------+   |
                |         |          |
                |    Admin action    |
                |    "Ship" +        |
                |    tracking info   |
                |         |          |
                |    +----v---+      |
                |    | SHIPPED|      |
                |    +----+--+      |
                |         |         |
                |    Admin action   |
                |    "Delivered"    |
                |         |         |
                |    +----v----+    |
                |    |DELIVERED|    |
                |    +---------+    |
                |                   |
                |   (Any status     |
                |    can also       |
                |    transition to) |
                |         |         |
          +-----v---+ +--v-------+
          |CANCELLED | | REFUNDED |
          +---------+ +----------+

Payment Status Flow:

PENDING ---> PAID ---> REFUNDED
   |           |
   v           v
 FAILED   PARTIALLY_REFUNDED

Key Transition Rules

• PENDING → CONFIRMED: Triggered automatically when payment succeeds (via /api/checkout/complete or Stripe webhook payment_intent.succeeded)
• PENDING → CANCELLED: Triggered by Stripe webhook payment_intent.canceled or admin action
• CONFIRMED → PROCESSING: Admin manually moves order to processing
• PROCESSING → SHIPPED: Admin adds tracking information
• SHIPPED → DELIVERED: Admin confirms delivery
• Any → CANCELLED: Admin cancellation (order status update)
• Any → REFUNDED: Full refund via Stripe webhook charge.refunded
• PAID → PARTIALLY_REFUNDED: Partial refund via Stripe webhook

Admin Actions

Order Detail Page

URL: /admin/orders/[id] Required permission: orders:read to view, orders:write to modify

Available admin actions (when orders:write permission is granted):

Refund Eligibility

The admin detail page calculates the refundable amount by:

1. Checking if a stripePaymentId exists on the order
2. Verifying payment status is PAID or PARTIALLY_REFUNDED
3. Retrieving the charge from Stripe to get amount_refunded
4. Returning max(0, total - totalRefunded)

Order List Page

URL: /admin/orders

Supports filtering by:

• Order status (enum dropdown)
• Payment status (enum dropdown)
• Pagination with configurable page size
• Sort order (ascending/descending by date)

Order Import

URL: Available via import dialog on orders list page

Supports bulk order creation from CSV or XLSX files. See Order Import section.

Notifications

Notification System

File: lib/notifications/order-notifications.ts

The notification system supports both in-app notifications and email alerts, configurable per admin user via OrderNotificationSetting.

Notification Types

Notification Settings

Each admin user has an OrderNotificationSetting record controlling:

Admin Notification Flow

When a new order is placed, notifyAdminsOfNewOrder() is called:

1. Fetches all users with ADMIN or DEVELOPER role
2. Creates ORDER_NEW notification for each admin (respecting their settings)
3. If order total >= $100, also creates ORDER_HIGH_VALUE notification

Notification Delivery

• In-app: Creates a Notification record in the database (title, message, entity reference)
• Email: Sends via sendEmail() with a link to the admin order detail page
• Mark as read: markNotificationAsRead() updates isRead flag and readAt timestamp

Order Modification

File: lib/orders/modify.ts

Admins can modify existing orders. The modifyOrder() function handles:

Modifiable Fields

Modification Process

1. Fetch existing order with items and shipping address
2. If items are updated: delete all existing OrderItem records, create new ones, recalculate subtotal
3. Recalculate total: subtotal + shippingCost + tax - discountAmount
4. Append modification to modificationHistory JSON array with timestamp, userId, and changes
5. Update order record
6. Create audit log entry (order.modify)

Modification History

Each modification is recorded in the order's modificationHistory JSON field:

{
  "timestamp": "2026-03-31T12:00:00.000Z",
  "userId": "clxxx...",
  "changes": {
    "before": { "items": [...] },
    "after": { "items": [...] }
  }
}

Order Import

File: lib/orders/import.ts

Supports bulk order creation from CSV or XLSX files.

Supported File Formats

• CSV — Parsed via PapaParse (headers required, empty lines skipped, # comments supported)
• XLSX/XLS — Parsed via ExcelJS (first worksheet, first row as headers)

Required Columns

Optional Columns

Import Options

Multi-Item Orders

Rows with the same orderNumber are grouped into a single order with multiple line items.

Auto-Generated Order Numbers

Format: ORD-YYYYMM-NNNNN (e.g., ORD-202603-00001), using sequential numbering within each month.

Validation Schemas

File: lib/validations/orders.ts

Zod schemas for all order operations:

Key Files