Delivered status records delivery date/time

Without a deliveredAt timestamp, any query for fulfillment metrics — average time from ship to delivery, on-time delivery rate, SLA compliance — becomes impossible or relies on updatedAt, which gets overwritten by post-delivery events like refund requests. If the customer contacts support asking when their package arrived, the platform has no answer beyond 'the carrier said so'. Capturing delivery time at the moment the status transitions is a one-line write that prevents a permanent data gap — a gap that can never be filled after the fact.

Add a nullable deliveredAt column to your order model in prisma/schema.prisma and populate it in lib/orders/state-machine.ts alongside other lifecycle timestamps.

// prisma/schema.prisma addition:
// deliveredAt DateTime?

// In transitionOrder (lib/orders/state-machine.ts):
const timestampFields: Record<string, Date> = {}
if (newStatus === 'delivered') timestampFields.deliveredAt = new Date()
if (newStatus === 'shipped')   timestampFields.shippedAt   = new Date()
if (newStatus === 'confirmed') timestampFields.confirmedAt = new Date()
if (newStatus === 'cancelled') timestampFields.cancelledAt = new Date()

await db.orders.update({ where: { id: orderId }, data: { status: newStatus, ...timestampFields } })

• ID: ecommerce-order-management.order-lifecycle.delivery-timestamp

• Severity: low

• What to look for: When an order transitions to delivered status, enumerate all fields written alongside the status change. Check whether a delivery timestamp is captured. Look for a deliveredAt column on the orders table or in the order schema (prisma/schema.prisma or equivalent). Find the code path that marks orders as delivered — count whether it is a carrier webhook, a manual admin action, or a customer confirmation flow — and verify that at least 1 timestamp field is written alongside the status change.

• Pass criteria: When an order reaches delivered status, a deliveredAt timestamp is recorded on the order record. The field exists in the database schema and is populated during the delivery transition. At least 1 delivery-specific field is written beyond just status.

• Fail criteria: Order status changes to delivered but no delivery timestamp is captured (0 delivery-specific fields written). The updatedAt field is the only approximation of when delivery occurred, and it gets overwritten if any future updates happen to the order (e.g., a refund request).

• Skip (N/A) when: Delivery status is not tracked by this application — the project delegates tracking entirely to a shipping carrier platform or third-party logistics provider and does not record a delivered state internally. No delivered status value exists in the codebase.

• Detail on fail: "Orders marked as delivered update only the status field. No deliveredAt timestamp is written. 0 delivery-specific fields captured. The only way to determine when an order was delivered would be to query the order_history table, if it exists."

• Remediation: Add a deliveredAt field to your order model (in prisma/schema.prisma) and populate it during the delivered transition in lib/orders/state-machine.ts:

  // Prisma schema addition (prisma/schema.prisma):
  // deliveredAt DateTime?
  
  // In transitionOrder (lib/orders/state-machine.ts):
  const timestampFields: Partial<Order> = { status: newStatus, updatedAt: new Date() }
  if (newStatus === 'delivered') timestampFields.deliveredAt = new Date()
  if (newStatus === 'confirmed') timestampFields.confirmedAt = new Date()
  if (newStatus === 'shipped')   timestampFields.shippedAt = new Date()
  if (newStatus === 'cancelled') timestampFields.cancelledAt = new Date()
  
  await db.orders.update({ where: { id: orderId }, data: timestampFields })
  

  Capturing all lifecycle timestamps makes it straightforward to display a delivery timeline to customers and to calculate fulfillment metrics (e.g., average time from confirmed to shipped).