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

[NicolasGorga]

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.

// Example usage

---

Checklist

Please ensure the following before requesting a review:

• 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
• The changes are covered by relevant tests
• I have verified the code works as intended locally
• 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

^{Written by Cursor Bugbot for commit 350a79e. This will update automatically on new commits. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: a6aa456

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 77 packages

Name	Type
@medusajs/core-flows	Patch
@medusajs/order	Patch
@medusajs/types	Patch
@medusajs/medusa	Patch
@medusajs/test-utils	Patch
integration-tests-http	Patch
@medusajs/event-bus-redis	Patch
@medusajs/draft-order	Patch
@medusajs/framework	Patch
@medusajs/js-sdk	Patch
@medusajs/modules-sdk	Patch
@medusajs/orchestration	Patch
@medusajs/utils	Patch
@medusajs/workflows-sdk	Patch
@medusajs/medusa-oas-cli	Patch
@medusajs/admin-bundler	Patch
@medusajs/dashboard	Patch
@medusajs/analytics	Patch
@medusajs/api-key	Patch
@medusajs/auth	Patch
@medusajs/caching	Patch
@medusajs/cart	Patch
@medusajs/currency	Patch
@medusajs/customer	Patch
@medusajs/file	Patch
@medusajs/fulfillment	Patch
@medusajs/index	Patch
@medusajs/inventory	Patch
@medusajs/link-modules	Patch
@medusajs/locking	Patch
@medusajs/notification	Patch
@medusajs/payment	Patch
@medusajs/pricing	Patch
@medusajs/product	Patch
@medusajs/promotion	Patch
@medusajs/rbac	Patch
@medusajs/region	Patch
@medusajs/sales-channel	Patch
@medusajs/settings	Patch
@medusajs/stock-location	Patch
@medusajs/store	Patch
@medusajs/tax	Patch
@medusajs/translation	Patch
@medusajs/user	Patch
@medusajs/workflow-engine-inmemory	Patch
@medusajs/workflow-engine-redis	Patch
@medusajs/cache-inmemory	Patch
@medusajs/cache-redis	Patch
@medusajs/event-bus-local	Patch
@medusajs/analytics-local	Patch
@medusajs/analytics-posthog	Patch
@medusajs/auth-emailpass	Patch
@medusajs/auth-github	Patch
@medusajs/auth-google	Patch
@medusajs/caching-redis	Patch
@medusajs/file-local	Patch
@medusajs/file-s3	Patch
@medusajs/fulfillment-manual	Patch
@medusajs/locking-postgres	Patch
@medusajs/locking-redis	Patch
@medusajs/notification-local	Patch
@medusajs/notification-sendgrid	Patch
@medusajs/payment-stripe	Patch
@medusajs/oas-github-ci	Patch
@medusajs/http-types-generator	Patch
@medusajs/cli	Patch
@medusajs/deps	Patch
@medusajs/telemetry	Patch
@medusajs/admin-sdk	Patch
@medusajs/admin-shared	Patch
@medusajs/admin-vite-plugin	Patch
@medusajs/icons	Patch
@medusajs/toolbox	Patch
@medusajs/ui-preset	Patch
create-medusa-app	Patch
medusa-dev-cli	Patch
@medusajs/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

9 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
api-reference	Ignored		Apr 10, 2026 9:19pm
api-reference-v2	Ignored	Preview	Apr 10, 2026 9:19pm
bloom-docs	Ignored	Preview	Apr 10, 2026 9:19pm
cloud-docs	Ignored	Preview	Apr 10, 2026 9:19pm
docs-ui	Ignored	Preview	Apr 10, 2026 9:19pm
docs-v2	Ignored	Preview	Apr 10, 2026 9:19pm
medusa-docs	Ignored	Preview	Apr 10, 2026 9:19pm
resources-docs	Ignored	Preview	Apr 10, 2026 9:19pm
user-guide	Ignored	Preview	Apr 10, 2026 9:19pm

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[github-actions]

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[medusa-os-bot]

Thank you for your contribution! 🎉

After an initial review, this PR looks good to us. Here's a summary:

✅ Linked to a verified issue (#14481)
✅ Changeset included
✅ Integration tests included
✅ Follows Medusa's conventions

A team member will do a final review before this is merged. We appreciate your patience!

---

Notes:

Adding metadata to the ExistingItem interface also affects OrderEditUpdateItemQuantityWorkflowInput, which is shared with the order-edit-update-item-quantity workflow (regular order edits). That workflow's transform does not include metadata in the action details it builds:

// packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts
details: {
  reference_id: item.id,
  quantity: item.quantity,
  unit_price: item.unit_price,
  compare_at_unit_price: item.compare_at_unit_price,
  quantity_diff: quantityDiff,
  // metadata is accepted by the type but silently dropped here
},

This means a caller using order-edit-update-item-quantity and passing metadata on items would have it silently discarded. Worth deciding whether to also update that workflow for consistency, or use a narrower type scoped to the draft order context.