Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 33 ยท Commerce Modules and the Data Model

Inventory, Stock Locations and Sales Channels

Understand how Medusa tracks stock: inventory items, levels, reservations, stock locations, sales channels, manage_inventory and backorders, with runnable stand-ins.

A product page can say "In stock", but behind that label Medusa answers three separate questions: what physical thing is this variant made of, where is it stored, and which of it is already promised to somebody. Medusa keeps those answers in different records so that one warehouse, many warehouses, bundles and backorders all work with the same small set of rules.

This lesson explains the records (inventory items, inventory levels, reservations), how a variant connects to them, how stock locations and sales channels decide which stock a storefront may sell, and what the two variant flags manage_inventory and allow_backorder change. The real Medusa code needs a running Medusa server with Postgres, so it is shown read-only. The runnable parts are plain-JavaScript stand-ins that follow the same arithmetic. General ideas such as "available equals on-hand minus reserved" are explained in Inventory Tracking and Reservations and Overselling; here we focus on how Medusa names and wires them.

The records and how they connect

Medusa's Inventory Module owns three kinds of records. The Product Module owns variants and the Stock Location Module owns locations. Modules are isolated, so they refer to each other through module links rather than foreign keys.

flowchart LR
    V["Product variant<br/>manage_inventory, allow_backorder"] -->|"link (required_quantity)"| II["Inventory item<br/>sku"]
    II --> IL["Inventory level<br/>stocked_quantity<br/>reserved_quantity"]
    IL --> SL["Stock location<br/>warehouse or store"]
    II --> R["Reservation item<br/>quantity, line_item_id"]
    R --> SL
    SC["Sales channel"] -->|"link"| SL

A variant is a thing customers choose; an inventory item is the physical stock; a level says how much of it sits in one location.

  • Inventory item: the stockable thing, with a SKU and a few physical attributes such as weight. It has no quantity of its own.
  • Inventory level: one row per inventory item and stock location. It holds stocked_quantity (what is on the shelf), reserved_quantity (what is promised to open orders) and incoming_quantity (what is on its way). The sellable number is derived: stocked_quantity - reserved_quantity.
  • Reservation item: a promise of a quantity of one inventory item at one location, usually tied to a cart or order line item through line_item_id.
  • Variant link: connects a product variant to one or more inventory items, each with a required_quantity. A single-bottle variant needs 1 bottle item. A "gift box of 3" variant can point at the same bottle item with required_quantity: 3, or at two different items (a bottle and a box) so a sale consumes both.

Splitting variant and inventory item looks like extra work for a single product, but it is what makes bundles, shared stock between variants and multi-warehouse selling possible without special cases. This builds on the variant ideas from Products, Variants and Options.

Stock locations and sales channels

A stock location is any place that holds inventory: a warehouse, a retail shop, a drop-shipper. It carries an address, and the fulfillment module later uses it to decide where shipping options can ship from.

A sales channel is a place where you sell: a web store, a mobile app, a B2B portal, a marketplace feed. A sales channel is linked to the stock locations that may supply it. This link is the scoping rule:

  • The storefront sends a publishable API key, and that key is tied to one or more sales channels (see The Store API).
  • When the Store API computes a variant's inventory_quantity, it only counts levels at stock locations linked to the key's sales channel.
  • When a cart is completed, Medusa reserves stock only from those locations.

So the "outlet store" channel can sell the outlet shop's stock while the "web" channel sells from the central warehouse, and neither can accidentally drain the other. A product is also assigned to sales channels, so a product can be hidden from a channel entirely.

Two flags on the variant

Two booleans on every variant control how the checkout treats it:

Flag Meaning
manage_inventory When true, Medusa checks availability and creates reservations. When false, the variant is always purchasable and no stock is tracked (good for digital goods, services or made-to-order items).
allow_backorder When true and inventory is managed, the variant may still be bought when available stock is zero or lower than the quantity. When false, the cart cannot be completed if there is not enough stock.

The combination matters. With manage_inventory: true and allow_backorder: false you get the strict "never oversell" behavior. With both true you get pre-orders: reservations are still created, and available quantity can drop below zero, which tells your warehouse how much to order from the supplier. With manage_inventory: false the other flag is irrelevant, because nothing is checked.

What happens at checkout

Completing a cart runs a workflow that, among other steps, confirms inventory and creates reservations. In simplified form:

  1. For each line item, find the variant's linked inventory items and multiply the line quantity by each required_quantity.
  2. Look up levels at the stock locations of the cart's sales channel (and the selected shipping option's location when relevant).
  3. If a variant has manage_inventory and not allow_backorder, fail the whole completion when the total available is too small. The order is not created and nothing is half-reserved.
  4. Otherwise create reservation items, which increase reserved_quantity and so lower availability for the next shopper.

Later, when an admin fulfills the order, the reservation is consumed: stocked_quantity goes down and the reservation disappears. If the order is canceled, the reservation is released. This life cycle (reserve, then consume or release) is the same one explained in Reservations and Overselling, and the failure rule is why checkout must be atomic.

Working with inventory in code

Inventory work in a Medusa backend goes through the Inventory Module's service or, more often, through core workflows. This is a read-only sketch of resolving the module and creating a level (the exact method names follow the module's generated CRUD naming; check your Medusa version):

TypeScript
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const inventory = req.scope.resolve(Modules.INVENTORY)

  const item = await inventory.createInventoryItems({ sku: "TENT-2P" })

  await inventory.createInventoryLevels({
    inventory_item_id: item.id,
    location_id: "sloc_warehouse",
    stocked_quantity: 25,
  })

  res.json({ inventory_item: item })
}

For anything that touches several modules, prefer the built-in workflows (for example the ones that create or adjust inventory levels and reservations), because they also run compensation when a step fails. You will see why in Compensation, Rollback and Long-Running Workflows.

Reading availability for a storefront is done by asking the Store API for the right fields, not by summing levels yourself. A read-only request looks like this:

HTTP
GET /store/products?fields=*variants,+variants.inventory_quantity
x-publishable-api-key: pk_...

The key decides the sales channel, the sales channel decides the locations, and the response carries one number per variant. Field syntax is covered in Query: Fields, Filters and Pagination.

Stand-in 1: levels, locations and sales-channel scoping

The first stand-in is not Medusa code. It reproduces the arithmetic: levels per item and location, a sales channel that sees only its own locations, kits through required_quantity, and the two flags.

Node.js Levels, locations and sales channels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the output: bottle-3pack is limited by the bottle count divided by 3, gift-set is limited by whichever of its two items runs out first, and the outlet channel cannot sell gift-set at all because no box is stocked at its location. The digital ebook and the backordered preorder-mug report Infinity because the flags switch the check off.

Stand-in 2: a reservation ledger that cannot oversell

The second stand-in adds reservations. reserve() is all-or-nothing, like a cart completion: if any line cannot be covered, no reservation is left behind. Fulfilling consumes stock and canceling releases it.

Node.js A reservation ledger that cannot oversell

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The important lines are the failed cart B and the pegs check right after it. Because the reservation loop validates every line before changing anything, the pegs were not reserved even though they were available. That is the property you want from Medusa's cart-completion workflow too: either the whole order is covered or none of it is held.

The ledger is single-threaded. Real Medusa runs on Postgres with many requests at once, and the Inventory Module must make reservation updates safe under concurrency. Never copy a "check then write" pattern like this into a production service without transactions or locks (see the atomic techniques in Reservations and Overselling).

Common mistakes

  • Putting quantity on the variant. There is no stock number on the variant. Quantity lives on levels, so setting up a variant without an inventory item and a level means "out of stock" for a store that manages inventory.
  • Forgetting the sales channel link. If a stock location is not linked to a sales channel, its stock is invisible to that channel's storefront, and shoppers see zero.
  • Using allow_backorder as a shortcut for unlimited stock. Backorder is a promise to ship later. Pair it with clear delivery messaging.
  • Disabling manage_inventory for physical goods to "fix" a stock problem. It silences the check and invites overselling.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does Medusa store the on-hand quantity of a product?

    Variants carry no stock number. An inventory level records stocked and reserved quantity for one inventory item at one stock location, and availability is stocked minus reserved.
  2. 2. What does required_quantity on the variant-to-inventory-item link let you model?

    A 3-pack variant can link to the single-bottle inventory item with required_quantity 3, so each sale consumes three units of the same stock.
  3. 3. A variant has manage_inventory true and allow_backorder true, and available stock is zero. What happens at cart completion?

    Backorders keep inventory managed, so the purchase is allowed and reservations still record the promise. Only manage_inventory false skips tracking altogether.
  4. 4. Why can the web sales channel show zero stock for an item that the outlet warehouse holds?

    Sales channels only count and reserve stock from the stock locations linked to them, which keeps channels from draining each other.

Summary

  • Inventory items are the stockable things, levels hold quantities per location, and reservations are promises tied to line items.
  • Variants link to inventory items with a required_quantity, which makes multipacks, kits and shared stock possible.
  • Sales channels are linked to stock locations, and that link scopes both the availability shown and the stock reserved.
  • manage_inventory switches tracking on or off; allow_backorder lets managed variants sell past zero.
  • Cart completion reserves stock all-or-nothing; fulfillment consumes it and cancellation releases it.

Next, see how storefronts read all of this through The Store API.