Integration Module 2.0 for Medusa is outRead the announcement
Webbers medusa logo

Webbers medusa

Quality-of-life admin customizations for Medusa v2 (notes, customer anonymization, guest order transfer, price-list discount control)

npm install @webbers/webbers-medusa
Category
Built by
Version
1.4.0
Last updated
1 month ago
Monthly downloads
Loading downloads

@webbers/webbers-medusa

Quality-of-life admin customizations for Medusa v2, extracted from the Frecious backend so they can be reused across projects.

Features

  • Notes — free-text notes on any entity, shown in the admin detail sidebar. Ships customer and order notes (with links + widgets); the generic module, endpoint and note component are reusable so other plugins can attach notes to their own entities (see "Attaching notes to your own entities").
  • Anonymize customer — AVG/GDPR data scrub for a customer across customer, cart and order records, plus any host-configured extra tables (superadmin only). See "Configuring extra tables".
  • Transfer guest orders — merge unassigned guest orders (matched by email) into a customer account.
  • Edit customer email — change a registered customer's email atomically across customer and auth identity, plus any host-configured extra tables (clears the cached Klaviyo id). See "Configuring extra tables".
  • Order discount breakdown — sidebar widget summarising the discount codes applied to an order, with amounts and percentages.
  • Order notifications — sidebar widget listing the transactional emails sent for an order.
  • Always-free promotion — flag a promotion as "always free shipping". Ships the data model, workflows, link and admin widget; the host app wires the trigger (see below).
  • Disallow price-list discounts — a toggle on the price-list detail page that stops discount/promotion codes from overriding that price list. Ships the data model, link, workflows, admin API + widget, and a store add-to-cart endpoint that enforces it; the storefront wires the endpoint (see below).
  • Product reviews — full product-review stack: module (reviews, responses, images, per-product stats), admin Reviews page (list + detail, approve/reject/flag, responses, link products), admin/store APIs (, , incl. image uploads, ) and an optional daily Kiyoh sync job. See "Product reviews".

Toggling features

The plugin adds a Settings → Webbers QoL page in the admin with a switch per feature. Toggling a feature off:

  • hides its admin widget — every widget reads the flags via and renders nothing when disabled; and
  • blocks its endpoints — a middleware returns for the feature's API routes (see ).

Flags are persisted by the bundled module (table ) and default to ON when no row exists, so the plugin is fully active out of the box. The canonical list of features lives in (shared by the server and admin builds).

Always-free is widget-only gating: disabling it hides the promotion switch, but the actual link is still written by the host app's promotion hooks, so leave the hooks in place if you rely on existing always-free promotions.

After installing, run the migration so the flag table exists:

npx medusa db:migrate

What's included

ConcernLocation
Feature catalog (single source of truth)
Settings module + migration (feature flags)
Settings admin page (Settings → Webbers QoL)
Note module + migration
Custom-query () module (raw SQL helpers, no migration)
Always-free () module + migration
Price-list-ext () module + migration
Links (customer/order note, promotion always-free, price-list-ext)
Workflows (note, always-free, price-list-ext)
Admin widgets
Admin API routes
Store API route (price-list-aware add-to-cart)
HTTP middlewares (note + edit-email validators, promotion , price-list-ext)

Installation

Install the plugin in your Medusa app:

Register it in the host app's :

After installing, run the migrations so the plugin's tables exist:

npx medusa db:migrate

The bundled module

The plugin bundles a module exposing / — the anonymize, transfer-guest-orders, edit-email and order-notifications routes resolve it from the container by key ().

Upgrading from ≤ 1.0.0: earlier versions required the host app to register its own module. That copy must now be removed (both the module directory and its entry) — two modules with the same key cannot coexist. The bundled module is a drop-in replacement (same key, same API, no migration/table).

This plugin has no dependency on any subscriptions package (or any other domain module). The anonymize / edit-email routines only touch , and tables out of the box; any extra tables (e.g. ) are declared by the host via plugin options — see "Configuring extra tables" below.

Configuring extra tables (anonymize / edit-email)

The anonymize and edit-email routines scrub the core Medusa tables on their own. To include tables owned by other modules — without this plugin depending on them — declare them in the plugin options in your . Every table/column name is validated () and all statements run inside the same transaction as the core scrub, so atomicity is preserved.

Product reviews

Ported from the former plugin — same module key (), table names and migration names, so an app that previously ran the standalone plugin upgrades in place with no data changes (remove the old plugin, keep this one, done).

Plugin options (in ):

The Kiyoh sync job runs daily but is a no-op unless these env vars are set in the host app:

It matches Kiyoh reviews to orders by (order display id) and creates product reviews through . With on (the default), it also copies each review's customer photo from Kiyoh to the host app's file provider and attaches it as a review image. The workflows are exported (, , , …) for host scripts, e.g. bulk imports or stats regeneration.

With configured, the admin review detail page gets a Translations section with a Translate button (), showing per language whether the translation is missing, up to date or outdated (the review was edited after translating). Translations are stored in the review's column, keyed by language, as ; nothing is translated automatically. Host apps decide what to translate with () and read translations with the helpers in .

The feature flag gates all review endpoints (admin + store) and the admin Reviews page content (the sidebar entry itself cannot be hidden dynamically; the page shows a notice when the feature is off).

Attaching notes to your own entities

The module, the endpoint ( / are free-form strings) and the note component are generic. To add notes to another entity from a separate plugin or your app — e.g. subscriptions — depend on and:

  1. Define the link between your module and the note module:

  2. Render a note widget in your entity's detail zone that calls with your (the module's registration key). The feature flag guards the endpoint, so the note stays hidden/blocked when notes are disabled in Settings → Webbers QoL.

This keeps the QoL plugin free of any dependency on your module while still owning the note storage.

Activating the always-free promotion behaviour

Toggling the widget writes on the promotion (the plugin's middleware whitelists that field). Turning that flag into an link requires a handler on Medusa's promotion workflow hooks. Medusa allows only one handler per workflow hook, and a real app usually does other work in / too — so the plugin does not register these hooks for you. Add them in your app's :

The plugin emits no (, to avoid a type-portability error), so these imports resolve to in the host app unless it sets . That is intentional — keep the casts above so the hook bodies stay type-checked.

Reading the flag elsewhere (e.g. a fulfillment provider deciding shipping is free) can join the link table directly:

Activating the disallow-price-list-discounts behaviour

The admin widget writes onto the price list's extended record (, linked to Medusa's ). The toggle only records intent — the enforcement happens when items are added to the cart.

The plugin ships the enforcement endpoint at . It behaves like Medusa's built-in add-to-cart, but when the body's points at a price list flagged , it sets on the line item (and stamps ). When the Disallow price-list discounts feature is toggled off, the endpoint skips that logic and behaves as a plain add-to-cart, so it is safe to call unconditionally.

To activate the behaviour, have the storefront add price-list items through this endpoint instead of the default :

Build