feat(core-flows,order,medusa,types): update item metadata on item_update change action (#14570)

NicolasGorga · web-flow · commit 9e1e7082c343 · 2026-04-10T21:29:15.000Z
## Summary **What** — What changes are introduced in this PR? Allow to update item `metadata` on `ITEM_UPDATE` order change action. **Why** — Why are these changes relevant or necessary? You are unable to update a draft order item `metadata`. **How** — How have these changes been implemented? Update item `metadata` if specified in the order change action details when the `ITEM_UPDATE` processing handler gets executed. **Testing** — How have these changes been tested, or how can the reviewer test the feature? Integration tests. --- ## Examples Provide examples or code snippets that demonstrate how this feature works, or how it can be used in practice. This helps with documentation and ensures maintainers can quickly understand and verify the change. ```ts // Example usage ``` --- ## Checklist Please ensure the following before requesting a review: - [x] I have added a **changeset** for this PR - Every non-breaking change should be marked as a **patch** - To add a changeset, run `yarn changeset` and follow the prompts - [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 Add any additional context, related issues, or references that might help the reviewer understand this PR. closes #14481 --- > [!NOTE] > Adds support for updating item `metadata` during draft order item updates. > > - Core flow `update-draft-order-item` now includes `metadata` in action `details` for `ITEM_UPDATE` > - Order processing merges provided `metadata` into both `item.detail.metadata` and `item.metadata` > - Types expanded to include optional `metadata` for new/existing items and related inputs > - Admin validators allow `metadata` in draft order item update payloads > - Order transform maps `detail.metadata` to exposed item `metadata` > - Integration test added to verify metadata update behavior > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 350a79e. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>
diff --git a/.changeset/seven-windows-brake.md b/.changeset/seven-windows-brake.md
@@ -0,0 +1,8 @@
+---
+"@medusajs/core-flows": patch
+"@medusajs/order": patch
+"@medusajs/types": patch
+"@medusajs/medusa": patch
+---
+
+feat(core-flows,order,medusa,types): update item metadata on item_update change action
diff --git a/integration-tests/http/__tests__/draft-order/admin/draft-order.spec.ts b/integration-tests/http/__tests__/draft-order/admin/draft-order.spec.ts
@@ -807,6 +807,97 @@ medusaIntegrationTestRunner({
 
         expect(reservations.length).toBe(0)
       })
+
+      it("should update item metadata", async () => {
+        // Create edit
+        await api.post(
+          `/admin/draft-orders/${testDraftOrder.id}/edit`,
+          {},
+          adminHeaders
+        )
+
+        // Add item with initial metadata
+        let orderPreview = (
+          await api.post(
+            `/admin/draft-orders/${testDraftOrder.id}/edit/items`,
+            {
+              items: [
+                {
+                  variant_id: product.variants.find(
+                    (v) => v.title === "L shirt"
+                  ).id,
+                  quantity: 1,
+                  metadata: { initial: "value", custom_field: "original" },
+                },
+              ],
+            },
+            adminHeaders
+          )
+        ).data.draft_order_preview
+
+        const itemToUpdate = orderPreview.items.find(
+          (i) => i.subtitle === "L shirt"
+        )
+        expect(itemToUpdate.metadata).toEqual({
+          initial: "value",
+          custom_field: "original",
+        })
+
+        await api.post(
+          `/admin/draft-orders/${testDraftOrder.id}/edit/confirm`,
+          {},
+          adminHeaders
+        )
+
+        await api.post(
+          `/admin/draft-orders/${testDraftOrder.id}/edit`,
+          {},
+          adminHeaders
+        )
+
+        // Update item with new metadata
+        orderPreview = (
+          await api.post(
+            `/admin/draft-orders/${testDraftOrder.id}/edit/items/item/${itemToUpdate.id}`,
+            {
+              quantity: 2,
+              metadata: { updated: "metadata", custom_field: "modified" },
+            },
+            adminHeaders
+          )
+        ).data.draft_order_preview
+
+        const updatedItem = orderPreview.items.find(
+          (i) => i.subtitle === "L shirt"
+        )
+        expect(updatedItem.quantity).toBe(2)
+        expect(updatedItem.metadata).toEqual({
+          updated: "metadata",
+          initial: "value",
+          custom_field: "modified",
+        })
+
+        await api.post(
+          `/admin/draft-orders/${testDraftOrder.id}/edit/confirm`,
+          {},
+          adminHeaders
+        )
+
+        const order = (
+          await api.get(
+            `/admin/draft-orders/${testDraftOrder.id}`,
+            adminHeaders
+          )
+        ).data.draft_order
+
+        expect(
+          order.items.find((i) => i.subtitle === "L shirt").metadata
+        ).toEqual({
+          updated: "metadata",
+          initial: "value",
+          custom_field: "modified",
+        })
+      })
     })
 
     describe("POST /draft-orders/:id/edit/promotions", () => {
diff --git a/packages/core/core-flows/src/draft-order/workflows/update-draft-order-item.ts b/packages/core/core-flows/src/draft-order/workflows/update-draft-order-item.ts
@@ -107,6 +107,7 @@ export const updateDraftOrderItemWorkflow = createWorkflow(
               unit_price: item.unit_price,
               compare_at_unit_price: item.compare_at_unit_price,
               quantity_diff: quantityDiff,
+              metadata: item.metadata,
             },
           }
         })
diff --git a/packages/core/core-flows/src/order/workflows/claim/claim-item.ts b/packages/core/core-flows/src/order/workflows/claim/claim-item.ts
@@ -45,14 +45,14 @@ export type OrderClaimItemValidationStepInput = {
 /**
  * This step validates that claim items can be added to a claim. If the
  * order or claim is canceled, or the order change is not active, the step will throw an error.
- * 
+ *
  * :::note
- * 
+ *
  * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
  * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
- * 
+ *
  * :::
- * 
+ *
  * @example
  * const data = orderClaimItemValidationStep({
  *   order: {
@@ -88,12 +88,12 @@ export const orderClaimItemValidationStep = createStep(
 
 export const orderClaimItemWorkflowId = "claim-item"
 /**
- * This workflow adds order items to a claim as claim items. It's used by the 
+ * This workflow adds order items to a claim as claim items. It's used by the
  * [Add Claim Items Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidclaimitems).
- * 
+ *
  * You can use this workflow within your customizations or your own custom workflows, allowing you to add items to a claim
  * for an order in your custom flows.
- * 
+ *
  * @example
  * const { result } = await orderClaimItemWorkflow(container)
  * .run({
@@ -107,9 +107,9 @@ export const orderClaimItemWorkflowId = "claim-item"
  *     ]
  *   }
  * })
- * 
+ *
  * @summary
- * 
+ *
  * Add order items to a claim as claim items.
  */
 export const orderClaimItemWorkflow = createWorkflow(
@@ -172,6 +172,7 @@ export const orderClaimItemWorkflow = createWorkflow(
             reference_id: item.id,
             reason: item.reason,
             quantity: item.quantity,
+            metadata: item.metadata,
           },
         }))
       }
diff --git a/packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts b/packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts
@@ -182,6 +182,7 @@ export const orderEditUpdateItemQuantityWorkflow = createWorkflow(
               unit_price: item.unit_price,
               compare_at_unit_price: item.compare_at_unit_price,
               quantity_diff: quantityDiff,
+              metadata: item.metadata,
             },
           }
         })
diff --git a/packages/core/types/src/http/claim/admin/payloads.ts b/packages/core/types/src/http/claim/admin/payloads.ts
@@ -30,6 +30,10 @@ interface AdminClaimAddItems {
      * An internal note viewed by admin users only.
      */
     internal_note?: string
+    /**
+     * Key-value pairs of custom data.
+     */
+    metadata?: Record<string, unknown> | null
   }[]
 }
 
@@ -120,13 +124,15 @@ export interface AdminCreateClaim {
 }
 
 export interface AdminAddClaimItems extends AdminClaimAddItems {}
-export interface AdminUpdateClaimItem extends Omit<AdminClaimUpdateItem, "description"> {}
+export interface AdminUpdateClaimItem
+  extends Omit<AdminClaimUpdateItem, "description"> {}
 
 export interface AdminAddClaimInboundItems extends AdminClaimAddItems {}
 export interface AdminUpdateClaimInboundItem extends AdminClaimUpdateItem {}
 
 export interface AdminAddClaimOutboundItems extends AdminClaimAddItems {}
-export interface AdminUpdateClaimOutboundItem extends Omit<AdminClaimUpdateItem, "description"> {}
+export interface AdminUpdateClaimOutboundItem
+  extends Omit<AdminClaimUpdateItem, "description"> {}
 
 export interface AdminClaimAddInboundShipping
   extends AdminClaimAddShippingMethod {}
diff --git a/packages/core/types/src/workflow/order/items.ts b/packages/core/types/src/workflow/order/items.ts
@@ -59,6 +59,10 @@ interface ExistingItem {
    * A note viewed by admins only related to the item.
    */
   internal_note?: string | null
+  /**
+   * Custom key-value pairs to store additional information about the item.
+   */
+  metadata?: Record<string, any> | null
 }
 
 /**
diff --git a/packages/medusa/src/api/admin/claims/validators.ts b/packages/medusa/src/api/admin/claims/validators.ts
@@ -164,6 +164,7 @@ export const AdminPostClaimItemsReqSchema = z.object({
       reason: z.nativeEnum(ClaimReason).optional(),
       description: z.string().optional(),
       internal_note: z.string().optional(),
+      metadata: z.record(z.string(), z.unknown()).nullish(),
     })
   ),
 })
@@ -212,4 +213,6 @@ export type AdminPostClaimsConfirmRequestReqSchemaType = z.infer<
 
 export const AdminDeleteClaimItemActionSchema = createSelectParams()
 
-export type AdminDeleteClaimItemActionSchemaType = z.infer<typeof AdminDeleteClaimItemActionSchema>
+export type AdminDeleteClaimItemActionSchemaType = z.infer<
+  typeof AdminDeleteClaimItemActionSchema
+>
diff --git a/packages/medusa/src/api/admin/draft-orders/validators.ts b/packages/medusa/src/api/admin/draft-orders/validators.ts
@@ -137,6 +137,7 @@ export const AdminUpdateDraftOrderItem = z.object({
   unit_price: z.number().nullish(),
   compare_at_unit_price: z.number().nullish(),
   internal_note: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).nullish(),
 })
 
 export type AdminUpdateDraftOrderActionItemType = z.infer<
diff --git a/packages/medusa/src/api/admin/order-edits/validators.ts b/packages/medusa/src/api/admin/order-edits/validators.ts
@@ -66,6 +66,7 @@ export const AdminPostOrderEditsUpdateItemQuantityReqSchema = z.object({
   unit_price: z.number().nullish(),
   compare_at_unit_price: z.number().nullish(),
   internal_note: z.string().nullish().optional(),
+  metadata: z.record(z.string(), z.unknown()).nullish(),
 })
 
 export type AdminPostOrderEditsUpdateItemQuantityReqSchemaType = z.infer<
diff --git a/packages/modules/order/src/services/order-module-service.ts b/packages/modules/order/src/services/order-module-service.ts
@@ -1157,6 +1157,7 @@ export default class OrderModuleService
           version: toCreate.version ?? 1,
           item_id: item.id,
           quantity: toCreate.quantity,
+          metadata: toCreate.metadata,
         })
       }
     }
diff --git a/packages/modules/order/src/types/line-item.ts b/packages/modules/order/src/types/line-item.ts
@@ -23,6 +23,7 @@ interface PartialUpsertOrderLineItemDTO {
   is_tax_inclusive?: boolean
 
   compare_at_unit_price?: BigNumberInput
+  metadata?: Record<string, unknown> | null
 }
 
 export interface CreateOrderLineItemDTO extends PartialUpsertOrderLineItemDTO {
diff --git a/packages/modules/order/src/types/utils/index.ts b/packages/modules/order/src/types/utils/index.ts
@@ -22,6 +22,7 @@ export type VirtualOrder = {
     unit_price: BigNumberInput
     compare_at_unit_price: BigNumberInput | null
     quantity: BigNumberInput
+    metadata?: Record<string, unknown> | null
     adjustments?: (LineItemAdjustmentDTO & { version: number })[]
     tax_lines?: LineItemTaxLineDTO[]
 
@@ -42,7 +43,7 @@ export type VirtualOrder = {
       return_received_quantity: BigNumberInput
       return_dismissed_quantity: BigNumberInput
       written_off_quantity: BigNumberInput
-      metadata?: Record<string, unknown>
+      metadata?: Record<string, unknown> | null
     }
   }[]
 
diff --git a/packages/modules/order/src/utils/actions/item-add.ts b/packages/modules/order/src/utils/actions/item-add.ts
@@ -1,7 +1,9 @@
 import {
   ChangeActionType,
+  isDefined,
   MathBN,
   MedusaError,
+  mergeMetadata,
 } from "@medusajs/framework/utils"
 import { VirtualOrder } from "@types"
 import { OrderChangeProcessing } from "../calculate-order-change"
@@ -22,6 +24,19 @@ OrderChangeProcessing.registerActionType(ChangeActionType.ITEM_ADD, {
         existing.detail.quantity,
         action.details.quantity
       )
+
+      if (isDefined(action.details.metadata)) {
+        const isUnset = action.details.metadata === null
+
+        if (isUnset) {
+          existing.metadata = null
+        } else {
+          existing.metadata = mergeMetadata(
+            existing.metadata ?? {},
+            action.details.metadata
+          )
+        }
+      }
     } else {
       existing = {
         id: action.details.reference_id!,
@@ -32,6 +47,9 @@ OrderChangeProcessing.registerActionType(ChangeActionType.ITEM_ADD, {
         unit_price: action.details.unit_price,
         compare_at_unit_price: action.details.compare_at_unit_price,
         quantity: action.details.quantity,
+        ...(action.details.metadata !== undefined
+          ? { metadata: action.details.metadata }
+          : {}),
       } as VirtualOrder["items"][0]
 
       currentOrder.items.push(existing)
diff --git a/packages/modules/order/src/utils/actions/item-update.ts b/packages/modules/order/src/utils/actions/item-update.ts
@@ -1,7 +1,9 @@
 import {
   ChangeActionType,
+  isDefined,
   MathBN,
   MedusaError,
+  mergeMetadata,
 } from "@medusajs/framework/utils"
 import { OrderChangeProcessing } from "../calculate-order-change"
 import { setActionReference } from "../set-action-reference"
@@ -27,6 +29,24 @@ OrderChangeProcessing.registerActionType(ChangeActionType.ITEM_UPDATE, {
     existing.quantity = currentQuantity
     existing.detail.quantity = currentQuantity
 
+    if (isDefined(action.details.metadata)) {
+      const isUnset = action.details.metadata === null
+
+      if (isUnset) {
+        existing.detail.metadata = null
+        existing.metadata = null
+      } else {
+        existing.detail.metadata = mergeMetadata(
+          existing.detail.metadata ?? existing.metadata ?? {},
+          action.details.metadata
+        )
+        existing.metadata = mergeMetadata(
+          existing.metadata ?? {},
+          action.details.metadata
+        )
+      }
+    }
+
     if (action.details.adjustments) {
       existing.adjustments = action.details.adjustments
     }
diff --git a/packages/modules/order/src/utils/transform-order.ts b/packages/modules/order/src/utils/transform-order.ts
@@ -55,6 +55,9 @@ export function formatOrder<T = any>(
         raw_compare_at_unit_price:
           detail.raw_compare_at_unit_price ??
           orderItem.item.raw_compare_at_unit_price,
+        metadata: isDefined(detail.metadata)
+          ? detail.metadata
+          : orderItem.item.metadata,
         detail,
       }
     })

Original file line number	Diff line number	Diff line change
`@@ -107,6 +107,7 @@ export const updateDraftOrderItemWorkflow = createWorkflow(`
`107`	`107`	`unit_price: item.unit_price,`
`108`	`108`	`compare_at_unit_price: item.compare_at_unit_price,`
`109`	`109`	`quantity_diff: quantityDiff,`
	`110`	`+ metadata: item.metadata,`
`110`	`111`	`},`
`111`	`112`	`}`
`112`	`113`	`})`
Original file line number	Diff line number	Diff line change
`@@ -182,6 +182,7 @@ export const orderEditUpdateItemQuantityWorkflow = createWorkflow(`
`182`	`182`	`unit_price: item.unit_price,`
`183`	`183`	`compare_at_unit_price: item.compare_at_unit_price,`
`184`	`184`	`quantity_diff: quantityDiff,`
	`185`	`+ metadata: item.metadata,`
`185`	`186`	`},`
`186`	`187`	`}`
`187`	`188`	`})`