apps/api/src/orders/order-repository.ts

@@ -98,6 +98,7 @@ export async function findOrderDetail(context: DatabaseContext, orderId: string)
     status: header.order.status as OrderDetail["status"],
     createdAt: header.order.createdAt,
     updatedAt: header.order.updatedAt,
+    notes: header.order.notes,
     customer: {
       id: header.customer.id,
       name: header.customer.name,
@@ -123,6 +124,10 @@ export async function updateOrderItemQuantity(context: DatabaseContext, itemId:
   await context.db.update(orderItems).set({ quantity }).where(eq(orderItems.id, itemId));
 }
 
+export async function updateOrderNotes(context: DatabaseContext, orderId: string, notes: string) {
+  await context.db.update(orders).set({ notes }).where(eq(orders.id, orderId));
+}
+
 export async function updateOrderTimestamp(context: DatabaseContext, orderId: string, updatedAt: string) {
   await context.db.update(orders).set({ updatedAt }).where(eq(orders.id, orderId));
 }

apps/api/src/orders/order-routes.ts

@@ -6,7 +6,7 @@ import { cancelOrder } from "./cancel-order";
 import { getOrder } from "./get-order";
 import { listAuditEvents } from "./list-audit-events";
 import { listOrders } from "./list-orders";
-import { changeOrderItemQuantity } from "./update-order-item";
+import { changeOrderItemQuantity, updateOrderNotes } from "./update-order-item";
 import { changeShippingAddress } from "./update-shipping-address";
 
 interface OrderRouteOptions {
@@ -33,6 +33,10 @@ interface CancelBody {
   reason?: string;
 }
 
+interface NotesBody {
+  notes: string;
+}
+
 type AuthenticatedRequest = FastifyRequest & { currentUser: AuthUser };
 
 export const registerOrderRoutes: FastifyPluginAsync<OrderRouteOptions> = async (app, options) => {
@@ -95,6 +99,31 @@ export const registerOrderRoutes: FastifyPluginAsync<OrderRouteOptions> = async
     return result.order;
   });
 
+  app.post<{ Params: IdParams; Body: NotesBody }>("/orders/:orderId/notes", {
+    schema: {
+      body: {
+        type: "object",
+        required: ["notes"],
+        properties: {
+          notes: { type: "string", maxLength: 1000 }
+        }
+      }
+    }
+  }, async (request, reply) => {
+    const currentUser = (request as AuthenticatedRequest).currentUser;
+    const result = await updateOrderNotes(options.db, {
+      orderId: request.params.orderId,
+      notes: request.body.notes,
+      actor: currentUser.username
+    });
+
+    if (result.statusCode !== 200) {
+      return reply.code(result.statusCode).send({ message: result.message });
+    }
+
+    return result.order;
+  });
+
   app.post<{ Params: IdParams; Body: Address }>("/orders/:orderId/shipping-address", {
     schema: {
       body: {

apps/api/src/orders/update-order-item.ts

@@ -1,6 +1,6 @@
 import type { DatabaseContext } from "../db/database";
 import { canEditOrderItems } from "./order-status";
-import { appendAuditEvent, findOrderDetail, findOrderItemRecord, updateOrderItemQuantity, updateOrderTimestamp } from "./order-repository";
+import { appendAuditEvent, findOrderDetail, findOrderItemRecord, updateOrderItemQuantity, updateOrderNotes as saveOrderNotes, updateOrderTimestamp } from "./order-repository";
 
 export async function changeOrderItemQuantity(
   context: DatabaseContext,
@@ -47,3 +47,44 @@ export async function changeOrderItemQuantity(
     order: await findOrderDetail(context, input.orderId)
   } as const;
 }
+
+export async function updateOrderNotes(
+  context: DatabaseContext,
+  input: {
+    orderId: string;
+    notes: string;
+    actor: string;
+  }
+) {
+  const order = await findOrderDetail(context, input.orderId);
+
+  if (!order) {
+    return { statusCode: 404, message: "Order not found." } as const;
+  }
+
+  const notes = input.notes.trim();
+
+  if (!notes) {
+    return { statusCode: 400, message: "Notes cannot be empty." } as const;
+  }
+
+  if (notes.length > 1000) {
+    return { statusCode: 400, message: "Notes must be 1000 characters or fewer." } as const;
+  }
+
+  const updatedAt = new Date().toISOString();
+  await saveOrderNotes(context, input.orderId, notes);
+  await updateOrderTimestamp(context, input.orderId, updatedAt);
+  await appendAuditEvent(context, {
+    orderId: input.orderId,
+    actor: input.actor,
+    type: "order.notes_updated",
+    message: "Updated internal order notes.",
+    createdAt: updatedAt
+  });
+
+  return {
+    statusCode: 200,
+    order: await findOrderDetail(context, input.orderId)
+  } as const;
+}

apps/web/src/orders/order-api.ts

@@ -21,6 +21,13 @@ export function updateOrderItemQuantity(orderId: string, itemId: string, quantit
   });
 }
 
+export function updateOrderNotes(orderId: string, notes: string) {
+  return apiRequest<OrderDetail>(`/api/orders/${orderId}/notes`, {
+    method: "POST",
+    body: JSON.stringify({ notes })
+  });
+}
+
 export function updateShippingAddress(orderId: string, address: Address) {
   return apiRequest<OrderDetail>(`/api/orders/${orderId}/shipping-address`, {
     method: "POST",

packages/shared/src/order-detail.ts

@@ -19,6 +19,7 @@ export interface OrderDetail {
   status: OrderStatus;
   createdAt: string;
   updatedAt: string;
+  notes: string | null;
   customer: CustomerSummary;
   shippingAddress: Address;
   items: OrderItemDetail[];