5. Inventory Management

[← Product Variants]/04-product-variants/ · [Index]/00-index/

5. Inventory Management

Verified against: Medusa admin dashboard 2.18.0 (inventory-detail, adjust-inventory, inventory-create, reservations — source-read directly), plus real seed data in services/medusa/src/migration-scripts/initial-data-seed.ts and .ai/features/inventory.md.

WARNING: Everything in this section describes the mechanics of the screens that exist. There is currently no real stock-tracking process behind them — every variant was seeded with a flat 1000 units as a placeholder, not a counted real quantity. Treat any number you see today as unverified until a real physical stock-take happens (see the upcoming [Stock Audit]/06-stock-audit/ section).

Core concepts, as this system actually models them

Every variant with “Manage Inventory” turned on automatically gets its own Inventory Item, which can then have a stock level at one or more Locations. Today there is exactly one location: “India Warehouse” (its address is a placeholder — the real warehouse address has not been confirmed).

At each location, three numbers are tracked:

In Stock (stocked_quantity) — the number physically on hand, as entered by a staff member. This is the only number you manually edit.
Reserved — held automatically by the system against orders that are placed but not yet fulfilled/shipped (a “Reservation,” created behind the scenes at checkout).
Available — calculated automatically as In Stock − Reserved. This is what actually limits whether a customer can buy more.

INFO: You never manually set “Available” or “Reserved” — they’re derived. The only field you ever type a number into is In Stock.

Receiving New Stock

There is no dedicated “Receive Stock” workflow or form in this admin — receiving stock in practice means going to Inventory → (the variant’s SKU) → Adjust Inventory and updating the In Stock number.

Real workflow, based on what the screen actually supports:

Purchase/production completed
      ↓
Stock physically received
      ↓
Staff opens Inventory → finds the SKU → Adjust Inventory
      ↓
Staff enters the new In Stock total (not an "amount added" — the absolute total)
      ↓
Save

IMPORTANT: The “In Stock” field is the new total quantity, not an increment. If you had 40 units and received 60 more, enter 100, not 60 — entering 60 would incorrectly overwrite your stock down to 60.

Fields from the original brief, and their real status

Field	Status
Product / SKU	Real — you select the item by its SKU before adjusting
Quantity	Real — the “In Stock” field described above
Batch/Lot	Not a field. Planned / Not yet implemented — see [Section 7 — Batch Management]/07-batch-management/
Manufacturing Date	Not a field. Planned / Not yet implemented
Expiry/Best Before Date	Not a field. Planned / Not yet implemented — worth flagging as a gap for food products specifically
Cost	Not a field. Planned / Not yet implemented — no cost-tracking exists anywhere in this admin
Supplier/source	Not a field. Planned / Not yet implemented
Storage location	Real, but limited — only one location (“India Warehouse”) exists; multi-location is supported by Medusa’s data model but hasn’t been set up here
Received Date	Not a field. The system records when the record was last edited internally, but there’s no user-facing “date received” field to fill in
Notes	Not a field. The Adjust Inventory screen has no notes/reason box — see the Warning below

WARNING — no audit trail on stock adjustments. The real “Adjust Inventory” screen has exactly one editable field (In Stock) and no reason, reference, or notes field. Whoever changes a quantity should keep their own record (e.g. a shared log) of why a number changed until a real audit-trail feature exists — the system itself won’t remember the reason. See the [Section 25 — Audit & Change History]/25-audit-and-change-history/.

Stock Adjustment

There is only one real mechanism for any kind of stock change today: editing the In Stock number on the Adjust Inventory screen. The system does not distinguish why the number changed.

Original brief concept	Real support
Stock increase	Enter a higher In Stock number
Stock decrease	Enter a lower In Stock number
Damaged stock	Enter a lower In Stock number — no “damaged” reason code exists, it looks identical to any other decrease
Lost stock	Same as above — no distinction
Expired stock	Same as above — no distinction, and no expiry-date field exists to even flag something as expired (see above)
Manual correction	Same mechanism — every adjustment is a “manual correction” in this system, there’s no separate flow
Stock count correction	Same mechanism

REQUIRED (process, not system-enforced): Until a real reason/audit field exists, always record why you changed a stock number somewhere outside the system (a shared note, a message to the team) — quantity, reason, and who made the change. The system will not do this for you.

Reservations

What it is: A hold placed automatically on stock when an order is created, so two customers can’t both “buy” the last unit. Visible under Inventory → Reservations, and on each inventory item’s own detail page.

What it contains, per reservation: the order line item it’s for, a description, the location, and that location’s In Stock / Reserved / Available numbers at the time.

When to check it: If a variant’s “Available” count looks wrong (lower than you expect), check Reservations first — stock may be correctly held against a real pending order, not actually missing.

Multi-location support

The system supports adding more than one stock location (via “Manage Locations” on an inventory item), but this has never been used — everything is at the single “India Warehouse” location today. This would become relevant if Sindhu Naturals ever operates from more than one warehouse/fulfillment point.

[← Product Variants]/04-product-variants/ · [Index]/00-index/ · [Next: Stock Audit →]/06-stock-audit/