[shahednasser]

Automated Documentation Updates

This PR accumulates automated documentation changes for the next release.
Each entry below corresponds to a merged commit that triggered updates.

Review carefully before merging. Claude may have missed context
or made incorrect assumptions.

---

1e8b4b6 — 2026-09-29

No documentation changes were needed. This commit is a security dependency bump of multer from ^2.3.0 to ^2.4.0 in @medusajs/medusa. It doesn't change any public API, configuration, or admin dashboard behavior.

Affected projects:

• book: Changes in: package.json (other)
• resources: Changes in: package.json (other)
• user-guide: Changes in: package.json (other)

---

fdac7de — 2026-09-29

Updated the Product Index Examples guide (resources/app/infrastructure-modules/search/product-index-examples) with a new "Changing Price Lists" section. It lists the new price-list.* events (available since v2.21.3), adds a priceListProductIds function that maps them to affected products through price_set_ids or the price list's prices, and adds the events to the complete index definition. The old note that said creating a price list doesn't emit an event now only covers price lists becoming active or expiring by date. The events reference is auto-generated, and the book didn't need changes.

Affected projects:

• book: Changes in: core-flows (core-flow), utils (framework)
• resources: Changes in: core-flows (core-flow), utils (framework)

---

7352313 — 2026-09-29

Added a "Manage Options" section to the Manage Products with the Admin API guide (resources/app/commerce-modules/product/guides/manage-with-admin-api). It explains how to add and remove product options with sdk.admin.product.linkOptions, which wasn't documented before. It also has a "Remove an Option from a Product with Variants" subsection for the new behavior (since v2.21.3): Medusa removes the option's values from the product's variants instead of throwing an error, and only fails when two variants would end up with the same option combination. The book didn't need changes.

Affected projects:

• book: Changes in: product (module)
• resources: Changes in: product (module)

---

e6510b1 — 2026-10-01

No documentation changes were needed. This commit fixes promiseAll from @medusajs/framework/utils so it no longer crashes when a promise rejects with a non-Error value, such as undefined, null, or a string. The function's signature and documented usage stay the same, so the existing examples in the book and resources still apply.

Affected projects:

• book: Changes in: utils (framework)
• resources: Changes in: utils (framework)

---

b561a37 — 2026-10-02

No documentation changes were needed. This commit adds a fetch option to the Search Module's cloud options and to the Medusa search provider options, which replaces the HTTP transport used to reach the Cloud search proxy. Both new options are tagged @ignore in their TSDoc, so they're internal and intentionally left out of the docs.

Affected projects:

• book: Changes in: search (module)
• resources: Changes in: search (module)

---

534b829 — 2026-10-05

Updated the Node.js requirement in the book and resources docs from "v20.19.0+ or v22.12.0+" to "v22.22.0+". Medusa dropped Node.js 20 support and now requires Node.js v22.22.0 or later. The change covers the Prerequisites lists in the installation, create-medusa-app, Medusa CLI, lint, Next.js Starter, recipe, tutorial, and integration guides, plus the /start prompt content and the v1-to-v2 migration guide. The Docker installation guide now uses the node:22-alpine base image. The user guide didn't need changes because the admin dashboard wasn't affected. The Cloud docs (cloud/app/projects/prerequisites and cloud/app/projects/clone-locally) still list the old requirement. This workflow can't edit them, so they need a separate update.

Affected projects:

• resources: Changes in: create-medusa-app (cli), utils (framework), package.json (other), package.json (other), package.json (other), package.json (other), draft-order (other), loyalty (other)
• book: Changes in: utils (framework), package.json (other), package.json (other), package.json (other), package.json (other), draft-order (other), loyalty (other)
• user-guide: Changes in: package.json (other), package.json (other), package.json (other), package.json (other), draft-order (other), loyalty (other)

---

09c7800 — 2026-10-07

No documentation changes were needed. This commit changes the status filter of BaseProductListParams in @medusajs/types so it only accepts an array of statuses, not a single status. No example in the book or resources passes status as a filter when listing products, and the HTTP types reference is auto-generated.

Affected projects:

• book: Changes in: types (framework)
• resources: Changes in: types (framework)

---

c522ce6 — 2026-10-08

This commit fixes the JS SDK's setLocale method so it logs a warning in server environments instead of throwing a ReferenceError. The docs didn't mention that setLocale only works in the browser, so a note now covers it in the JS SDK guide (resources/app/js-sdk, "Localization with JS SDK" section) and the Localization storefront guide (resources/app/storefront-development/localization). Both notes point to the "Set Locale in Server Environments" section, which explains how to pass the x-medusa-locale header instead. The book didn't need changes.

Affected projects:

• book: Changes in: js-sdk (framework)
• resources: Changes in: js-sdk (framework)

---

b34706a — 2026-10-09

No documentation changes were needed. This commit only fixes a "seperate" typo in a code comment in the design-system toolbox's color token utility (packages/design-system/toolbox/src/commands/tokens/utils/colors.ts). It doesn't change token generation, component behavior, or any public API.

Affected projects:

• book: Changes in: toolbox (design-system)
• resources: Changes in: toolbox (design-system)
• ui: Changes in: toolbox (design-system)

---

780a69a — 2026-10-09

Added a "Retry Refunds Safely with an Idempotency Key" section to the Payment Flow guide (resources/app/commerce-modules/payment/payment-flow). It shows how to pass the new idempotency_key (since v2.21.3) to refundPaymentWorkflow and the Payment Module's refundPayment method, and to the Refund Payment admin API route. It also explains how a retry behaves when the previous refund succeeded, failed, is still pending, or used a different amount. Notes cover the new refund status property (pending, succeeded, failed) and that refundPaymentWorkflow returns the payment without the new refund. The book didn't need changes, and the user guide didn't either because the admin dashboard wasn't changed.

Affected projects:

• book: Changes in: core-flows (core-flow), types (framework), utils (framework), src (other), payment (module)
• resources: Changes in: core-flows (core-flow), types (framework), utils (framework), src (other), payment (module)
• user-guide: Changes in: src (other)

---

06bc7ec — 2026-10-16

No documentation changes were needed. This commit removes an undefined allowed property from the query config of the admin customers export route (packages/medusa/src/api/admin/customers/query-config.ts). It's an internal bug fix that doesn't change the route's public API, and the admin dashboard wasn't changed. The API reference is managed separately.

Affected projects:

• book: Changes in: src (other)
• resources: Changes in: src (other)
• user-guide: Changes in: src (other)

---

b3db8ec — 2026-10-19

No documentation changes were needed. This commit fixes the update method of the AuthIdentityProviderService that Medusa passes to auth providers. The method now updates the provider identity whose entity_id matches, instead of the first identity from the same provider. Its signature and documented usage stay the same, so the existing examples in the Phone Authentication tutorial and the Okta integration guide still apply, and the auth provider reference is auto-generated.

Affected projects:

• book: Changes in: auth (module)
• resources: Changes in: auth (module)

---

673d03e — 2026-10-19

Documented the new projectConfig.http.requireActorAssociation option. It makes an auth provider, such as emailpass, only authenticate auth identities already associated with the requested actor type. The book's Medusa Configurations chapter (book/app/learn/configurations/medusa-config) has a new http.requireActorAssociation section after http.authMethodsPerActor, and the Auth Providers guide (resources/app/commerce-modules/auth/auth-providers) has a new "Require Actor Association for Auth Providers" section. Both explain the default behavior, the generic Authentication failed error, and that registration isn't affected. The version notes say v2.22.0 because pending changesets include minor bumps (for example, the Node.js 20 drop), while earlier entries in this PR use v2.21.3, so confirm the release version before merging. The user guide didn't need changes because the admin dashboard wasn't changed.

Affected projects:

• book: Changes in: types (framework), src (other)
• resources: Changes in: types (framework), src (other)
• user-guide: Changes in: src (other)

---

3755f0f — 2026-10-20

Documented the HTTP tracing changes in the book's Instrumentation chapter (book/app/learn/debugging-and-testing/instrumentation). The instrument.http option of registerOtel now accepts an object with an allowedQueryParams property, and a new "Configure HTTP Tracing" section explains the new behavior: Medusa strips the query string from http.url and span names, reports it in a url.query attribute with values of non-allowed parameters replaced by REDACTED, and no longer reports sensitive headers such as authorization and cookie. The Sentry integration guide (resources/app/integrations/guides/sentry) links to the new section. The version notes say v2.22.0 to match the previous entry, so confirm the release version before merging. The user guide didn't need changes because the admin dashboard wasn't changed.

Affected projects:

• book: Changes in: src (other)
• resources: Changes in: src (other)
• user-guide: Changes in: src (other)

[medusa-agents]

Thanks for the contribution! Initial automated review looks good. Reviewed on 45d93c9.

[medusa-agents]

The review above was truncated in submission; here is its full text, unchanged from the automated reviewer (still reviewed on 45d93c9, triggered by: new commit pushed): Thanks for the contribution! Initial automated review looks good. This docs-only PR collects the automated doc updates for the next release. We checked the new content against the source code: - HTTP tracing (instrumentation chapter): instrument.http accepts an object (packages/medusa/src/instrumentation/index.ts). The default allowedQueryParams list, the REDACTED replacement, base-name matching for array params, * passthrough, stripping the query from http.url and span names, and the sensitive-header pattern all match the implementation. - http.requireActorAssociation: the behavior matches packages/medusa/src/api/auth/[actor_type]/[auth_provider]/route.ts, including the generic Authentication failed error and the {actor_type}_id check on app_metadata. The #httprequireActorAssociation anchor follows the existing #httpauthMethodsPerActor convention. - Refund idempotency (payment-flow): the documented retry behavior matches resolveRefundRequest_ in the Payment Module. An amount mismatch throws an error. A pending refund throws CONFLICT, and is only retried once it has been pending for more than 15 minutes. A succeeded refund is replayed and a failed one is retried. - Price list events (product-index-examples): the event names and the price_set_ids payload match packages/core/utils/src/core-flows/events.ts. The new priceListProductIds example calls relatedProductIds with its existing signature and reuses the deleted flag from resolveProductIds. - Node.js requirement and setLocale notes: these are consistent text updates across the prerequisites and the two localization pages. Notes: - As the PR body says, earlier entries use v2.21.3 in their version notes and later ones use v2.22.0. Confirm the release version before merging. - The Cloud docs (cloud/app/projects/prerequisites and cloud/app/projects/clone-locally) still list the old Node.js requirement and need a separate update.