3. Product Management

[← Admin Dashboard]/02-admin-dashboard/ · [Index]/00-index/

3. Product Management

Verified against: Medusa admin dashboard 2.18.0 product-create/product-edit/variant-edit forms (source-read directly), plus the real seed data in services/medusa/src/migration-scripts/initial-data-seed.ts.

Add New Product

Medusa’s product creation screen is a 4-step wizard: Details → Organize → Variants → Inventory Kit (the last step only appears if you choose to track stock per-location during creation). The fields below are grouped to match the original wiki brief, with a note on which wizard step each one is actually entered in.

IMPORTANT: Several fields the original brief expects at the product level (Barcode, Weight, Dimensions, HS Code, MID Code, Country of Origin) are actually variant-level fields in this system — each size (250ml/500ml/1000ml) has its own. They’re entered by opening a variant and editing it, not on the main product form. See Variant Identification & Attributes below.

Basic Information

(Details step)

Field	Required?	Notes
Product Name (Title)	REQUIRED
Subtitle	OPTIONAL	Short secondary line under the title
Description	OPTIONAL	Long-form text
Handle (URL Slug)	REQUIRED, auto-filled	Auto-generated from the title; can be edited. This is the closest thing to “Product Type” or a product-level SEO field that exists in this admin

Not in this admin as separate fields — Planned / Not yet implemented:

Product Type exists as a field, but it’s set on the Organize step (see below), not Basic Information.
Brand — no dedicated field. Would need to go in Description or a custom metadata field (see product metadata below) — not currently done for either existing product.
Visibility and Featured Product — no dedicated toggle exists. The closest real control is Product Status (below) and Sales Channel assignment.

Status & Publishing

(set via a Status field on the product, and via the Details-step “Save as draft” vs. “Publish” choice during creation)

Medusa’s real product status values (confirmed in source, @medusajs/utils ProductStatus enum):

draft
proposed
published
rejected

INFO: The creation wizard only lets you choose Draft or Publish directly. proposed and rejected are only reachable by editing an existing product’s Status field afterward.

Publishing checklist (Draft → Review → Publish):

Draft — product exists but is not visible on the storefront. Use this while filling in fields.
Before moving to Published, verify:
- Title, description are correct and typo-free
- At least one variant exists with a real price (not the ₹0 default)
- Real product images are uploaded (not a placeholder)
- HSN code and GST rate are set in metadata (see below) — GST invoicing will fail loud for an order containing a product with no HSN code (.ai/features/gst.md)
- Inventory quantity is set to a real number, not left at 0 (unless genuinely out of stock)
Published — visible on the storefront (assuming it’s assigned to the right Sales Channel — see Organize step).

WARNING: There is no “Review” status distinct from proposed in the way the original brief implies a formal review queue — proposed exists as a value but nothing in this system currently enforces or uses a review workflow around it. Treat “Draft → Publish” as the real two-step flow today.

Product Identification

Field	Where it actually lives
SKU	Per variant, not per product — set on the Variants step / each variant’s edit page
Barcode, EAN, UPC	Per variant, on that variant’s own edit page (see below)
Internal Product ID	Medusa auto-assigns an internal ID; no separate user-facing field to set your own
HSN/SAC	Stored in product metadata as `hsn_code`, not a dedicated admin field — see below
Tax/GST classification	Stored in product metadata as `gst_rate`, not a dedicated admin field — see below

IMPORTANT — do not invent tax values. HSN 1507 and 5% GST are what this store’s two existing products use, sourced from the brand’s own product packaging/asset package, not independently verified as legally correct — see docs/gst-assumptions.md in the codebase. A qualified tax professional should confirm these before treating them as compliant.

HSN/GST/FSSAI metadata (real fields used by this store)

Because Medusa’s product form has no dedicated HSN/GST/FSSAI UI fields, this store puts them in the generic product metadata key-value section instead. The two existing products both carry:

hsn_code: "1507"
gst_rate: "5%"
fssai_number: "21226007000605"
extraction_method: e.g. "Wood Cold Pressed"

When adding a new product, enter these same keys in the product’s metadata section so GST invoicing and any future FSSAI display keep working consistently. There is no dropdown/validation on these — they’re free-text key-value pairs, so a typo’d key (e.g. hsn-code instead of hsn_code) will silently not be picked up anywhere. Double-check spelling against the values above.

Pricing

(Variants step, or a variant’s own Pricing tab)

Pricing is set per variant, not per product — there is no single “product price.”

Field	Notes
Selling Price	Entered directly per variant, per currency (this store uses INR only)
Cost Price	Not a field in this admin. Planned / Not yet implemented — no cost-tracking exists
MRP	Not a separate field. This store’s Selling Price is the MRP — no separate MRP-vs-selling-price distinction exists in the admin today
Discount / Discount Type	Handled via Promotions, not a per-product field — see [02-admin-dashboard.md]/02-admin-dashboard/#promotions-coupons—discounts. Not used yet
Tax-inclusive/exclusive setting	Controlled at the Region/Tax Region level (Settings), not per product
Effective selling price	= the price entered, plus GST calculated at checkout by the tax provider (CGST+SGST or IGST depending on buyer state) — calculated automatically, not something you enter

Real example (both existing products, same across sizes):

Size	Price
250ml	₹140
500ml	₹260
1000ml	₹500

INFO: Which values are business inputs vs. calculated: you enter the base selling price per variant. The system calculates GST on top of it at checkout (CGST/SGST if the buyer is in the same state as the seller — Karnataka — otherwise IGST), and the final invoice total. You never manually enter a tax amount.

Inventory

(Inventory Kit step during creation, or the Inventory section afterward)

Field	Notes
Track Inventory	= “Manage Inventory” toggle, per variant
Stock Quantity	Entered per variant, per stock location (today: one location, “India Warehouse”)
Low Stock Threshold	Not a field in this admin. Planned / Not yet implemented — no low-stock alerting exists
Stock Status	Derived automatically from quantity (in stock / out of stock) — not manually set
Allow Backorders	Real toggle, per variant
Stock Location	Only one exists today: “India Warehouse” (its address is a placeholder — real warehouse address not yet confirmed)
Batch/Lot Number	Not a field in this admin. Planned / Not yet implemented — see the upcoming Batch Management section

Product Details (food/oil-specific)

IMPORTANT: do not assume actual values for any product you didn’t personally source this information for.

None of these have dedicated admin fields — for both existing products they’re either folded into the free-text Description, or (for HSN/GST/FSSAI) into metadata as described above:

Net Quantity / Unit — implied by the variant title (e.g. “500ml”), not a separate structured field
Ingredients, Packaging Type, Storage Instructions, Shelf Life, Country of Origin (business sense, e.g. “Product of India”), Manufacturer/packer info, Usage information — Planned / Not yet implemented as structured fields; would currently need to go in Description or metadata if needed

INFO: “Country of Origin” does exist as a real field — but at the variant level, as a logistics/customs field (ISO country code), not a marketing “Product of India” field. See Variant Identification & Attributes.

Images

(Details step → Media, or a product’s Media section afterward)

Medusa’s model is simpler than the original brief’s field list: there is one image gallery per product, plus a flag marking which single image is the Thumbnail.

Original brief field	Reality in this admin
Main Product Image	The gallery image marked “Make thumbnail”
Gallery Images	The rest of the uploaded gallery
Thumbnail	Same mechanism as above — any gallery image can be toggled as the thumbnail
Product Label Image, Lifestyle Image	No dedicated field/type — just additional gallery images, distinguished only by filename/order, not by the system
Image Alt Text	Not a field in this admin. Planned / Not yet implemented — Medusa doesn’t expose alt-text editing here

Real example: both existing products’ seed data uses a hero shot, a back-label shot, a cooking-context shot, and a “why choose us” shot as gallery images — see services/medusa/seed-assets/products/ in the codebase for the actual files if you need a reference for what “good” product photography looks like for this brand.

SEO

Status: mostly Planned / Not yet implemented.

Original brief field	Reality
URL Slug	Real — this is the Handle field (Basic Information, above)
SEO Title, Meta Description, Keywords, Open Graph image	Not fields in this admin at all. No dedicated SEO fields exist in Medusa’s default product form

If SEO metadata becomes a real requirement, it will need either a custom admin widget/field or to be handled entirely on the storefront/Next.js side — not something a staff member can currently set from the dashboard.

Variant Identification & Attributes

Opening an individual variant (from the product’s Variants list) gives you the fields the original brief expected at the product level:

Inventory group:

SKU
EAN
UPC
Barcode
Manage Inventory (toggle)
Allow Backorders (toggle)

Attributes group:

Weight
Width / Length / Height
MID code
HS code
Country of Origin

Real example — both products use the same weight pattern across their 3 sizes:

Size	SKU pattern	Weight
250ml	`SINDHU-GRN-250` / `SINDHU-COC-250`	230g
500ml	`SINDHU-GRN-500` / `SINDHU-COC-500`	460g
1000ml	`SINDHU-GRN-1000` / `SINDHU-COC-1000`	920g

WARNING: SKUs for the two products are easy to confuse at a glance (GRN = Groundnut, COC = Coconut) — always check the letters, not just the number, before adjusting stock or price on the wrong variant.

Full variant-vs-product-vs-SKU workflow, and the “when should I add a new variant vs. a new product” question, is covered in [Section 4 — Product Variants]/04-product-variants/.

[← Admin Dashboard]/02-admin-dashboard/ · [Index]/00-index/ · [Next: Product Variants →]/04-product-variants/