8. Order Management

[← Batch Management]/07-batch-management/ · [Index]/00-index/

8. Order Management

Verified against: Medusa admin dashboard 2.18.0 (order-detail, order-general-section, order-fulfillment-section, order-payment-section, order-create-refund, lib/order-helpers.ts — source-read directly), plus .ai/features/orders.md, .ai/features/payments.md, .ai/features/gst.md, .ai/features/checkout.md.

WARNING — read this before anything else in this section. As of this wiki being written, no order has ever been completed end-to-end through a real payment on this system (.ai/features/orders.md, .ai/features/checkout.md). Everything below describes what the screens are built to do, verified by reading the actual dashboard code — not something confirmed by real order volume yet. Treat early real orders as something to double-check carefully, not routine.

Correcting a assumption from the original brief

The original wiki spec assumed a single linear order status: Created → Payment Pending → Payment Confirmed → Confirmed → Processing → Packed → Shipped → Delivered. That single track doesn’t exist in this system. Medusa actually tracks two independent statuses per order, plus a separate canceled flag:

Payment status:       not_paid → authorized/captured → (refunded if needed)
Fulfillment status:   not_fulfilled → fulfilled → shipped → delivered
Canceled:             a separate flag, can happen at almost any point

Both are shown as badges at the top of every order’s detail page. An order can be, for example, “captured” + “not_fulfilled” at the same time — paid but not yet packed/shipped. Read both badges, not one combined status.

Payment status values

(exact values from the dashboard source, lib/order-helpers.ts)

Status	Meaning	Who changes it	What happens next
`not_paid`	No successful payment yet	System, at order creation	Customer completes payment, or the order stalls/gets abandoned
`awaiting`	Payment session started but not confirmed	System	Should resolve automatically once the customer finishes checkout
`requires_action`	Payment needs manual follow-up (e.g. a 3-D Secure step didn’t complete)	System flags it; staff investigates	Use the Check Status button on the order’s Payment section to re-poll Razorpay, or contact the customer
`authorized`	Payment approved but funds not yet captured	System (on successful checkout)	Staff clicks Capture to actually take the funds
`partially_authorized`	Only part of the order total was authorized	System	Investigate — this is unusual, not a normal step
`captured`	Funds have been taken — this is a “paid” order	Staff, via the Capture action (or automatic capture, if configured)	Proceed to fulfillment
`partially_captured`	Only part of the order was captured	Staff (partial capture)	Uncommon — verify why before proceeding
`refunded`	Full amount refunded	Staff, via the Refund action	Order is effectively closed out financially
`partially_refunded`	Some amount refunded	Staff, via the Refund action (supports partial amounts)	Order remains open for the un-refunded portion
`canceled`	Payment was canceled	System/staff	No funds were or will be taken

INFO: The Capture and Refund actions live in the order’s Payment section (inside the order detail page), not a separate “Payments” area of the admin — see [02-admin-dashboard.md]/02-admin-dashboard/#payments.

IMPORTANT: Razorpay is in test mode today (.ai/features/payments.md) — no real money moves regardless of what “captured” shows. Don’t treat a captured test payment as real revenue.

Fulfillment status values

(exact values from the dashboard source)

Status	Meaning	Who changes it	What happens next
`not_fulfilled`	Nothing has been packed/handed to a carrier yet	Default at order creation	Staff picks/packs, then clicks Fulfill Items
`partially_fulfilled`	Some line items fulfilled, not all	Staff (fulfilling a subset of items)	Fulfill the remaining items separately
`fulfilled`	All items packed into a fulfillment record	Staff, via Fulfill Items	Staff adds tracking and marks as shipped
`partially_shipped` / `shipped`	Tracking added, marked as shipped	Staff, via Mark as Shipped (adds tracking number/URL)	Customer/system awaits delivery
`partially_delivered` / `delivered`	Marked delivered	Staff, via Mark as Delivered	Order lifecycle is complete
`partially_returned` / `returned`	Items came back from the customer	Staff, via the return workflow (see below)	Refund/credit note as applicable
`canceled`	The fulfillment itself was canceled (before shipping)	Staff, via Cancel on that fulfillment	Items become available to fulfill again or the order is canceled
`requires_action`	Something needs manual attention (e.g. a shipping label failed)	System flags it; staff investigates	Check the fulfillment provider (see Shiprocket note below)

Order-level cancellation

A whole order can be canceled via the action menu on the order detail page (separate from canceling one fulfillment). This shows a confirmation warning before proceeding.

IMPORTANT — real, verified consequence of canceling an order: Canceling an order through this admin action automatically triggers this project’s own GST credit note generation (a real, built feature — see .ai/features/gst.md, and the upcoming [Invoicing]/16-invoicing/ / [Refunds & Returns]/15-refunds-and-returns/ sections). This only happens if a GST invoice was actually issued for that order in the first place — if none exists, credit note generation is skipped, not fabricated.

TO BE CONFIRMED: There is no customer-facing self-service cancellation on the storefront today — cancellation only happens from this admin action. Whether/when self-service cancellation should be added is a business decision, not yet made.

Failed payments, partial refunds, partial cancellation — real support level

Original brief concept	Real support in this system
Failed payment	Surfaces as `requires_action` or the order simply never reaches `authorized`/`captured`. Server-side `authorizePayment` independently re-verifies with Razorpay — the storefront’s payment button is never trusted alone (`.ai/features/payments.md`)
Cancelled order	Real — see above. Whole-order only from the admin’s Cancel action
Refund	Real — Refund action on the order’s Payment section. Fields: which payment (if more than one), Amount (supports partial), Refund Reason (dropdown, sourced from Settings → Refund Reasons), Note (free text) — this is one of the few places in the admin that does capture a reason, unlike stock adjustments
Partial refund	Real — the Amount field accepts less than the full payment
Partial cancellation	Not the same mechanism as full order cancellation. Removing individual line items from an order before fulfillment, or handling post-fulfillment adjustments, uses Medusa’s separate Order Edit / Claim / Exchange / Return flows (all exist as real screens in this admin — `order-create-edit`, `order-create-claim`, `order-create-exchange`, `order-create-return`). Full field-level detail on these is deferred to [Refunds & Returns]/15-refunds-and-returns/ rather than duplicated here

Shipping/fulfillment note

Fulfillment uses Medusa’s default manual_manual provider — marking something as fulfilled or shipped in the admin does not automatically talk to a real courier (.ai/features/shipping.md). A Shiprocket integration exists in the codebase to create a real courier order/AWB/label on fulfillment, but it’s blocked on a real Shiprocket account for end-to-end testing — don’t assume tracking numbers are being generated automatically until this is confirmed live.

[← Batch Management]/07-batch-management/ · [Index]/00-index/ · [Next: Order Processing SOP →]/09-order-processing-sop/