Order Notes

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/order-notes/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants need to document special handling instructions (gift wrap, fragile, expedited shipping, customer preferences) per order. This feature stores and displays notes without changing order data.

The problem

I manually write notes on order print-outs (gift wrap, fragile, customer color preference), but when the order moves to another location or person, those notes are lost. I need a structured place to keep notes that travels with the order.

What it does

• Add notes collection: {id, order_id, timestamp, user_id, content, type (internal|customer_facing)}
• Allow staff to add notes to any order from order detail page
• Display notes list in order detail, newest first
• Support internal notes (staff only) and customer-facing notes (can be shown in order tracking page if storefront supports it)
• Timestamp and author name on each note
• Allow editing/deleting own notes (with audit trail: ‘edited by X at time Y’)
• Soft-delete notes (hide from view but keep audit trail)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Templated notes (e.g., ‘Gift wrap’, ‘Fragile’) — that is UX convenience, can be plugin with shortcuts
• Collaborative note mentions (@user notifications) — that is real-time features, separate feature
• Note threading/replies — that is conversation feature, defer to plugin

Data model

notes collection: {id, order_id, timestamp, user_id, content, type, edited_at, edited_by_id, deleted_at}. Migration: new collection.

API

• POST /api/admin/orders/:orderId/notes — add note
• GET /api/admin/orders/:orderId/notes — list notes for order
• PATCH /api/admin/orders/:orderId/notes/:noteId — edit note
• DELETE /api/admin/orders/:orderId/notes/:noteId — delete note (soft-delete)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Order detail page includes ‘Notes’ section. Text input to add new note (with toggle ‘internal’ vs ‘customer-facing’). Notes list shows: timestamp, author name, note content, edit/delete buttons. Deleted notes show as ‘deleted by X at time Y’ for audit trail.

The seam — why this is core

Core owns notes storage and UI. No paid seam — order documentation is infrastructure.

Core owns the interface + honest note storage; order management is infrastructure, not a per-country obligation or credential.

Dependencies

• Existing orders collection
• existing admin dashboard

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Add a note to order and confirm notes collection stores content, timestamp, user_id, and order_id
• Verify note appears in order detail page immediately after creation
• Edit a note and confirm edited_at and edited_by_id are recorded
• Soft-delete a note and confirm note is hidden from view but edit history log shows ‘deleted by X’
• Verify ‘internal’ toggle changes note type correctly

Risks

Notes can be used for sensitive info (customer complaints, payment disputes). Ensure notes are not exposed in public APIs and that edit history is immutable. Implement permission checks: staff can see all notes, but only admins can delete (soft-delete still audited).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.