Medusa v2 Multi-Location Inventory: Why Checkout Fails on Stock You Actually Have

I have spent enough time in workflow engines to know that the expensive bugs are never the ones in the code you wrote — they are the ones where two correct-looking steps hold different opinions about the same number. I am Manoj, commerce and ERP implementation lead at Mith Tech in Bengaluru, and multi-warehouse Medusa builds are a large part of what our team ships.

The two steps that disagree

Two separate pieces of code answer the question "is there enough stock?" and they answer it differently.

The confirm side sums. prepareConfirmInventoryInput attaches a location_ids array to every item using a three-tier fallback. First it tries locationsWithAvailability — the locations where one location alone covers the whole line. When that list is empty (A holds 1, B holds 1, the line needs 2), it falls through to locationsWithLevel: every location that merely stocks the item. That multi-element array is handed to confirmInventory, which calls retrieveAvailableQuantity with the whole array, and the inventory level repository sums across all of them. 1 + 1 = 2 ≥ 2 → true. Add-to-cart succeeds.

The reserve side takes index zero. In reserveInventoryStep, the items map builds one reservation per line item at the full line quantity, with location_id: item.location_ids[0]. The array is silently truncated. The inventory module's createReservationItems then runs ensureInventoryLevels with validateQuantityAtLocation: true, compares the level's available_quantity against the requested quantity, and throws:

Error Type: not_allowed
Not enough stock available for item <inventory_item_id> at location <location_id>

A sibling error from the same guard fires when the item is not stocked at the chosen location at all: Item <inventory_item_id> is not stocked at location <location_id>, as not_found.

I read reserve-inventory.ts at ?ref=v2.18.0. The line location_id: item.location_ids[0], is present and unmodified. This ships in the current release.

The simulator below is the whole bug in one panel. Set the per-location numbers, set the cart line, and watch the confirm step pass while the reserve step fails on the same inputs.

Error Type: not_allowed
Not enough stock available for item iitem_01JX9 at location sloc_A

The control case matters as much as the failure. Give Warehouse A two units instead of one and the bug vanishes — locationsWithAvailability is now non-empty, location_ids has exactly one element, and index [0] is correct. The bug only fires when no single channel-linked location can cover the line on its own. That is why it never shows up in development and always shows up after you add a second warehouse.

Why the order already exists

Inside completeCartWorkflow, the ordering in the create-order branch is:

So the sequence is: add-to-cart passes on aggregate stock → order row created → reservation throws → workflow compensates. Depending on where compensation lands, you get failed checkouts and order rows that never completed. Reconcile those before you trust your order count.

location_ids[0] is not your primary warehouse

It is worth being precise about what index zero actually is, because a lot of teams assume it is configurable.

location_ids is the set of stock locations that both (a) hold an InventoryLevel for one of the cart's inventory items and (b) are linked to the cart's sales_channel_id through the sales_channel_stock_location link table. That link is many-to-many on both sides: one channel can have N locations, one location can serve N channels. Order within the array is Set insertion order — that is, whatever order the query graph returned rows in.

There is no priority field. No "default location" setting. No proximity calculation. location_ids[0] is effectively arbitrary, and can change between deploys.

What you would try first, and why it cannot work

This is the part that cost real time, so here it is in full.

Attempt one: a workflow hook. Medusa's entire customisation story is hooks, so the natural move is to find the hook around the reservation and override the location. completeCartWorkflow calls createHook exactly three times: validate, beforePaymentAuthorization, and orderCreated. The latter two are @ignored in the type signature but are registered at runtime — createHook unconditionally calls context.hookBinder, and create-workflow.ts builds mainFlow.hooks[hook] for every declared hook. So you can call them. It just does not help: both sit after the parallelize block containing the reserve step. By the time either fires, the reservation has already thrown. Only validate runs early enough, and it has no mechanism to influence which location the reservation uses.

Attempt two: re-register the workflow. If there is no hook, define your own createWorkflow("complete-cart", …) and let yours load last. This throws at boot. WorkflowManager.register JSON.stringify-compares the incoming flow against the registered one and raises Workflow with id "complete-cart" and step definition already exists. when they differ — and a different step graph is exactly what you are trying to register.

Both roads are closed. That leaves a clone under a new name plus a route override as the only approach that both fixes the behaviour and boots. The decider below walks the full set, including the two mitigations that work but cost you something.

The fix that works

Three files. A split-reservation step that greedily fills across location_ids in line-item units, a clone of complete-cart.ts under the id complete-cart-split, and a route override that calls the workflow engine with the new id.

The split algorithm is adapted from the live diff of PR #15327. Two APIs it uses could not be verified against v2.18.0's source and are marked UNVERIFIED inline: MathBN.mod / MathBN.div, and the array-filter typing of listInventoryLevels. Check both signatures against your installed version before you ship. If MathBN.mod and MathBN.div are not exported, plain integer arithmetic is safe — required_quantity is typed number in both step interfaces.

Note also that the greedy fill works in line-item units, not raw inventory units. A required_quantity: 3 variant must not receive a 4-unit allocation, because 4 cannot be mapped back to an integer number of line items at fulfillment.

// src/workflows/steps/reserve-inventory-split.ts
// Userland adaptation of the algorithm in unmerged PR #15327.
// Preserves core's compensation contract: returns { reservations, inventoryItemIds }
// and deletes the reservations on rollback.

import { MathBN, Modules } from "@medusajs/framework/utils"
import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
import type {
  BigNumberInput,
  IInventoryService,
  InventoryTypes,
} from "@medusajs/framework/types"

// Same shape as core's ReserveVariantInventoryStepInput
export interface ReserveInventorySplitStepInput {
  items: {
    id?: string
    inventory_item_id: string
    required_quantity: number
    allow_backorder: boolean
    quantity: BigNumberInput
    location_ids: string[]
  }[]
}

const availabilityKey = (inventoryItemId: string, locationId: string) =>
  `${inventoryItemId}::${locationId}`

async function buildReservationInputs(
  items: ReserveInventorySplitStepInput["items"],
  inventoryService: IInventoryService
): Promise<InventoryTypes.CreateReservationItemInput[]> {
  // Only managed, non-backorder items with >1 candidate location can be split
  const itemsToSplit = items.filter(
    (i) => !i.allow_backorder && i.location_ids.length > 1
  )

  let availabilityByKey: Map<string, BigNumberInput> | null = null

  if (itemsToSplit.length) {
    const inventoryItemIds = Array.from(
      new Set(itemsToSplit.map((i) => i.inventory_item_id))
    )
    const locationIds = Array.from(
      new Set(itemsToSplit.flatMap((i) => i.location_ids))
    )

    // UNVERIFIED: the array-filter typing of listInventoryLevels was NOT
    // confirmed against v2.18.0's IInventoryService. Check the signature in
    // your installed version. If arrays are rejected, use:
    //   { inventory_item_id: { $in: inventoryItemIds },
    //     location_id: { $in: locationIds } }
    const levels = await inventoryService.listInventoryLevels({
      inventory_item_id: inventoryItemIds,
      location_id: locationIds,
    })

    availabilityByKey = new Map(
      levels.map((l) => [
        availabilityKey(l.inventory_item_id, l.location_id),
        MathBN.sub(l.stocked_quantity, l.reserved_quantity),
      ])
    )
  }

  const result: InventoryTypes.CreateReservationItemInput[] = []

  for (const item of items) {
    const totalNeeded = MathBN.mult(item.required_quantity, item.quantity)

    // Backorder / single location / no data => core behaviour, untouched
    if (
      item.allow_backorder ||
      item.location_ids.length <= 1 ||
      !availabilityByKey
    ) {
      result.push({
        line_item_id: item.id,
        inventory_item_id: item.inventory_item_id,
        quantity: totalNeeded,
        allow_backorder: item.allow_backorder,
        location_id: item.location_ids[0],
      })
      continue
    }

    // Greedy-fill in LINE-ITEM units, not raw inventory units, so every
    // allocation is a whole multiple of required_quantity. Otherwise a
    // required_quantity=3 variant can get a 4-unit allocation that cannot be
    // mapped back to an integer number of line-item units at fulfillment.
    let remainingUnits: BigNumberInput = item.quantity
    const splitEntries: InventoryTypes.CreateReservationItemInput[] = []

    for (const locationId of item.location_ids) {
      if (MathBN.lte(remainingUnits, 0)) break

      const available = availabilityByKey.get(
        availabilityKey(item.inventory_item_id, locationId)
      )
      if (available === undefined || MathBN.lte(available, 0)) continue

      // UNVERIFIED: MathBN.mod and MathBN.div are used by PR #15327 but their
      // existence on the exported MathBN in v2.18.0 was NOT confirmed. Check
      // before shipping. required_quantity is typed number in both step
      // interfaces, so plain integer math on Number(available.toString()) is a
      // safe substitute if these members are missing.
      const remainder = MathBN.mod(available, item.required_quantity)
      const usable = MathBN.sub(available, remainder)
      if (MathBN.lte(usable, 0)) continue

      const availableUnits = MathBN.div(usable, item.required_quantity)
      const takeUnits = MathBN.lte(availableUnits, remainingUnits)
        ? availableUnits
        : remainingUnits

      splitEntries.push({
        line_item_id: item.id,
        inventory_item_id: item.inventory_item_id,
        quantity: MathBN.mult(takeUnits, item.required_quantity),
        allow_backorder: item.allow_backorder,
        location_id: locationId,
      })

      remainingUnits = MathBN.sub(remainingUnits, takeUnits)
    }

    if (MathBN.gt(remainingUnits, 0)) {
      // Aggregate genuinely insufficient: fall back to one reservation at the
      // first location so the inventory module raises the canonical
      // "Not enough stock available…" error and the error contract is preserved.
      result.push({
        line_item_id: item.id,
        inventory_item_id: item.inventory_item_id,
        quantity: totalNeeded,
        allow_backorder: item.allow_backorder,
        location_id: item.location_ids[0],
      })
    } else {
      result.push(...splitEntries)
    }
  }

  return result
}

export const reserveInventorySplitStepId = "reserve-inventory-split-step"

export const reserveInventorySplitStep = createStep(
  reserveInventorySplitStepId,
  async (data: ReserveInventorySplitStepInput, { container }) => {
    if (!data.items.length) {
      return new StepResponse([], { reservations: [], inventoryItemIds: [] })
    }

    const inventoryService = container.resolve(Modules.INVENTORY)
    const locking = container.resolve(Modules.LOCKING)

    const inventoryItemIds = data.items.map((i) => i.inventory_item_id)
    const lockingKeys = Array.from(new Set(inventoryItemIds))

    const reservations = await locking.execute(lockingKeys, async () => {
      const inputs = await buildReservationInputs(data.items, inventoryService)
      return await inventoryService.createReservationItems(inputs)
    })

    return new StepResponse(reservations, {
      reservations: reservations.map((r) => r.id),
      inventoryItemIds,
    })
  },
  async (data, { container }) => {
    if (!data?.reservations?.length) return

    const inventoryService = container.resolve(Modules.INVENTORY)
    const locking = container.resolve(Modules.LOCKING)
    const lockingKeys = Array.from(new Set(data.inventoryItemIds))

    await locking.execute(lockingKeys, async () => {
      await inventoryService.deleteReservationItems(data.reservations)
    })

    return new StepResponse()
  }
)

The route override works because core resolves the workflow by id string through the workflow engine — we.run(completeCartWorkflowId, …) — so swapping the id in your own route file is sufficient and you never import the workflow function. Medusa's routes loader documents that duplicate routes are won by whichever is registered last, and application routes under src/api are scanned after core routes.

Medusa's own documentation on overriding API routes discourages same-path override and recommends replicating at a new path instead. If you can change your storefront, mount at src/api/store/carts/[id]/complete-split/route.ts and call that. Functionally identical, safer on upgrades.

Two honest costs. Cloning complete-cart.ts copies roughly four hundred lines of promotion, tax, payment and link logic that Medusa will keep changing — budget for a re-diff on every minor upgrade. And splitting the reservation is only half the job: once one line item carries two reservations at two locations, createOrderFulfillmentWorkflow has to consume them per-location. Both upstream PRs touch create-fulfillment.ts for exactly that reason. Ship the split without the fulfillment change and you have moved the failure from checkout to fulfillment.

If cloning is too much surface, the lower-effort route is patching @medusajs/core-flows directly with the reserve-inventory.ts hunk from PR #15327 via yarn patch or patch-package. That PR also ships 389 lines of unit tests, including a case named for issue #14987 — port those into your own suite so the patch is regression-guarded. The trade-off is that you are patching compiled output, patches break on every version bump, and the behaviour change applies to every consumer of reserveInventoryStep in your app, including draft-order conversion, order edits, claims and exchanges.

Before you run multi-warehouse on v2 today

The checklist below is what we work through on a Medusa store with more than one stock location per sales channel. The blockers are the ones that decide whether you have a live failure waiting to happen.

Where upstream is going

PR #16246, opened 2026-07-30, introduces a reserveInventoryWorkflow and replaces the bare step call in complete-cart.ts with a runAsStep invocation, exposing a setReservationAllocations hook to customise which stock locations quantities are reserved at — in-store pickup being the headline use case — while createOrderFulfillmentWorkflow learns to consume reservations at the fulfillment's location first. That is precisely what the community asked for on issue #14987.

It is unmerged. I read the changeset and the complete-cart.ts hunk, not the full workflow file, so the exact hook input and return contract is unverified — do not write against that signature yet. Track the PR; do not build on it.

Worth correcting two things that get repeated. Issue #16115 is closed as completed, and it is a different multi-location bug — Admin Create Fulfillment reading .location.id off an array — not this one. And issue #14987 was closed not_planned by a stale bot after three stale windows, not rejected by a maintainer; the reporter asked for it to be reopened on the day it closed and it has not been.

There is no third-party writeup of this bug anywhere — no dev.to post, no Stack Overflow answer, no Medusa blog entry. The only record is four GitHub issues and two unmerged pull requests, and the canonical issue was closed by a bot. If you run more than one stock location per sales channel on Medusa v2.18.0, you have this bug whether or not you have noticed it yet; the simulator above will tell you in five seconds. Fix it before your warehouse team rebalances stock and discovers it for you.