fix(core-flows): honor item-level allow_backorder when confirming inventory (#15731)

## Summary

**What** — Honor item-level `allow_backorder` when confirming inventory for draft-order items. This allows admins to add out-of-stock variants to a draft order by setting `allow_backorder: true` on the item, regardless of the variant's own backorder setting.

**Why** — Addresses the inventory-confirmation part of #14106. Although `allow_backorder` was accepted by the admin API, it was dropped before inventory confirmation, causing out-of-stock variants to be rejected even when backordering was explicitly requested.

**How** —

* Updated `prepareConfirmInventoryInput` to consider item-level `allow_backorder` alongside the variant configuration.
* Threaded `allow_backorder?: boolean` through `NewItem` and `ConfirmVariantInventoryWorkflowInputDTO["items"]` so the value reaches `confirmInventoryStep`.
* Applied the same logic to sales-channel stock-location validation.
* Backward compatible: the field is optional and store cart endpoints do not accept it.

**Testing** —

* Added unit tests covering item-level backorder overrides and stock-location validation behavior.
* Added integration tests verifying that out-of-stock variants are rejected without the flag and accepted when `allow_backorder: true` is provided.

---

## Examples

```ts
await api.post(`/admin/draft-orders/${draftOrderId}/edit/items`, {
  items: [
    {
      variant_id: "variant_123",
      quantity: 1,
      allow_backorder: true,
    },
  ],
})
```

---

## Checklist

* [x] I have added a **changeset** for this PR (patch: `@medusajs/core-flows`, `@medusajs/types`)
* [x] The changes are covered by relevant **tests**
* [x] I have verified the code works as intended locally
* [x] I have linked the related issue(s) if applicable

---

## Additional Context

Related to #14106.

This PR only addresses the inventory-confirmation bug. The reservation-linking concern mentioned in the issue remains out of scope.

Author: shafi-VM

.changeset/draft-order-allow-backorder.md

@@ -0,0 +1,8 @@
+---
+"@medusajs/core-flows": patch
+"@medusajs/types": patch
+---
+
+fix(core-flows,types): respect item-level allow_backorder when confirming inventory
+
+When adding an item, the `allow_backorder` flag passed on the item is now honored during inventory confirmation, overriding the variant's own `allow_backorder` setting for that item only. Previously the flag was accepted by the API but ignored, making it impossible to add an out-of-stock variant to a draft order even with `allow_backorder: true`.

integration-tests/http/__tests__/draft-order/admin/draft-order.spec.ts

@@ -1831,5 +1831,105 @@ medusaIntegrationTestRunner({
         )
       })
     })
+
+    describe("POST /draft-orders/:id/edit/items - allow_backorder", () => {
+      let outOfStockProduct
+      let outOfStockInventoryItem
+
+      beforeEach(async () => {
+        outOfStockInventoryItem = (
+          await api.post(
+            `/admin/inventory-items`,
+            { sku: "out-of-stock-sku" },
+            adminHeaders
+          )
+        ).data.inventory_item
+
+        // A location level exists for the sales channel, but with no
+        // available stock, so the variant is out of stock.
+        await api.post(
+          `/admin/inventory-items/${outOfStockInventoryItem.id}/location-levels`,
+          {
+            location_id: stockLocation.id,
+            stocked_quantity: 0,
+          },
+          adminHeaders
+        )
+
+        outOfStockProduct = (
+          await api.post(
+            "/admin/products",
+            {
+              title: "Out of stock product",
+              status: ProductStatus.PUBLISHED,
+              options: [{ title: "size", values: ["large"] }],
+              variants: [
+                {
+                  title: "L shirt",
+                  options: { size: "large" },
+                  manage_inventory: true,
+                  allow_backorder: false,
+                  inventory_items: [
+                    {
+                      inventory_item_id: outOfStockInventoryItem.id,
+                      required_quantity: 1,
+                    },
+                  ],
+                  prices: [{ currency_code: "usd", amount: 10 }],
+                },
+              ],
+            },
+            adminHeaders
+          )
+        ).data.product
+
+        await api.post(
+          `/admin/draft-orders/${testDraftOrder.id}/edit`,
+          {},
+          adminHeaders
+        )
+      })
+
+      it("should not allow adding an out-of-stock variant without allow_backorder", async () => {
+        const variantId = outOfStockProduct.variants[0].id
+
+        const error = await api
+          .post(
+            `/admin/draft-orders/${testDraftOrder.id}/edit/items`,
+            { items: [{ variant_id: variantId, quantity: 1 }] },
+            adminHeaders
+          )
+          .catch((e) => e)
+
+        expect(error.response.status).toBe(400)
+        expect(error.response.data.message).toContain(
+          "does not have the required inventory"
+        )
+      })
+
+      it("should allow adding an out-of-stock variant when allow_backorder is true on the item", async () => {
+        const variantId = outOfStockProduct.variants[0].id
+
+        const response = await api.post(
+          `/admin/draft-orders/${testDraftOrder.id}/edit/items`,
+          {
+            items: [
+              { variant_id: variantId, quantity: 1, allow_backorder: true },
+            ],
+          },
+          adminHeaders
+        )
+
+        expect(response.status).toBe(200)
+        expect(response.data.draft_order_preview.items).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              variant_id: variantId,
+              quantity: 1,
+            }),
+          ])
+        )
+      })
+    })
   },
 })

packages/core/core-flows/src/cart/utils/__tests__/prepare-confirm-inventory-input.spec.ts

@@ -325,6 +325,119 @@ describe("prepareConfirmInventoryInput", () => {
     })
   })
 
+  it("if an item opts into allow_backorder, it should override a variant that doesn't allow backorder", () => {
+    const input = {
+      sales_channel_id: "sc_1",
+      variants: [
+        {
+          id: "pv_1",
+          manage_inventory: true,
+          allow_backorder: false,
+          inventory_items: [
+            {
+              inventory_item_id: "ii_1",
+              variant_id: "pv_1",
+              required_quantity: 1,
+              inventory: [
+                {
+                  location_levels: {
+                    stocked_quantity: 0, // out of stock
+                    reserved_quantity: 0,
+                    location_id: "sl_1",
+                    stock_locations: [
+                      {
+                        id: "sl_1",
+                        sales_channels: [{ id: "sc_1" }],
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      items: [
+        {
+          variant_id: "pv_1",
+          quantity: 1,
+          id: "item_1",
+          allow_backorder: true,
+        },
+      ],
+    }
+
+    const result = prepareConfirmInventoryInput({ input })
+
+    expect(result).toEqual({
+      items: [
+        {
+          id: "item_1",
+          inventory_item_id: "ii_1",
+          required_quantity: 1,
+          quantity: 1,
+          allow_backorder: true,
+          location_ids: ["sl_1"],
+        },
+      ],
+    })
+  })
+
+  it("if an item opts into allow_backorder, it should return normally even if there's no stock location for the sales channel", () => {
+    const input = {
+      sales_channel_id: "sc_1",
+      variants: [
+        {
+          id: "pv_1",
+          manage_inventory: true,
+          allow_backorder: false,
+          inventory_items: [
+            {
+              inventory_item_id: "ii_1",
+              variant_id: "pv_1",
+              required_quantity: 1,
+              inventory: [
+                {
+                  location_levels: {
+                    stock_locations: [
+                      {
+                        id: "sl_2",
+                        sales_channels: [{ id: "sc_2" }], // Different sales channel
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      items: [
+        {
+          variant_id: "pv_1",
+          quantity: 1,
+          id: "item_1",
+          allow_backorder: true,
+        },
+      ],
+    }
+
+    const result = prepareConfirmInventoryInput({ input })
+
+    expect(result).toEqual({
+      items: [
+        {
+          id: "item_1",
+          inventory_item_id: "ii_1",
+          required_quantity: 1,
+          quantity: 1,
+          allow_backorder: true,
+          location_ids: [],
+        },
+      ],
+    })
+  })
+
   it("should return only stock locations with availability, if any", () => {
     const input = {
       sales_channel_id: "sc_1",

packages/core/core-flows/src/cart/utils/prepare-confirm-inventory-input.ts

@@ -56,6 +56,7 @@ interface ConfirmInventoryPreparationInput {
     id?: string
     variant_id?: string | null
     quantity: BigNumberInput
+    allow_backorder?: boolean
   }[]
   variants: {
     id: string
@@ -98,6 +99,15 @@ export const prepareConfirmInventoryInput = (data: {
 
   const salesChannelId = data.input.sales_channel_id
 
+  // Variants for which an item explicitly opts into backorder, overriding the
+  // variant's own `allow_backorder` setting (e.g. an admin adding an
+  // out-of-stock item to a draft order).
+  const itemBackorderVariantIds = new Set(
+    (data.input.items ?? [])
+      .filter((item) => item.allow_backorder && item.variant_id)
+      .map((item) => item.variant_id as string)
+  )
+
   for (const updateItem of data.input.itemsToUpdate ?? []) {
     const updateItem_ = "data" in updateItem ? updateItem.data : updateItem
 
@@ -190,7 +200,8 @@ export const prepareConfirmInventoryInput = (data: {
       if (
         variant.manage_inventory &&
         !variantsWithLocationForChannel.has(variant.id) &&
-        !variant.allow_backorder
+        !variant.allow_backorder &&
+        !itemBackorderVariantIds.has(variant.id)
       ) {
         throw new MedusaError(
           MedusaError.Types.INVALID_DATA,
@@ -269,7 +280,7 @@ const formatInventoryInput = ({
         id: item.id,
         inventory_item_id: variantInventoryItem.inventory_item_id,
         required_quantity: variantInventoryItem.required_quantity,
-        allow_backorder: !!variant.allow_backorder,
+        allow_backorder: !!variant.allow_backorder || !!item.allow_backorder,
         quantity: item.quantity,
         location_ids: locationsWithAvailability.length
           ? locationsWithAvailability

packages/core/types/src/cart/workflows.ts

@@ -510,6 +510,11 @@ export interface ConfirmVariantInventoryWorkflowInputDTO {
      * The ID of the line item if it's already in the cart.
      */
     id?: string
+    /**
+     * Whether the item can be added even if its variant is out of stock. This
+     * overrides the variant's `allow_backorder` setting for this item only.
+     */
+    allow_backorder?: boolean
   }[]
   /**
    * The new quantity of the variant to be added to the cart.

packages/core/types/src/workflow/order/items.ts

@@ -29,6 +29,11 @@ interface NewItem {
    * A note viewed by admins only related to the item.
    */
   internal_note?: string | null
+  /**
+   * Whether the item can be added even if its variant is out of stock. This
+   * overrides the variant's `allow_backorder` setting for this item only.
+   */
+  allow_backorder?: boolean
   /**
    * Custom key-value pairs to store additional information about the item.
    */