MedusaでEC構築する判断基準｜構成・費用・日本対応の実態【2026年最新】

Medusa（メデューサ）は、Node.jsとTypeScriptで書かれたオープンソースのコマースエンジンです。EC機能をAPIとして提供し、画面側は自由に作る「ヘッドレス」型で、日本でもShopifyやEC-CUBEの代替候補として名前が挙がるようになりました。ただし国内の導入記事は公式サイトの要約が多く、決済・税・移行という実装で必ず詰まる箇所がほとんど書かれていません。この記事では2026年8月12日時点の一次情報をもとに、構成・費用・日本運用の制約を数値で示します。

まとめ

Medusaの最新版は2.18.0（2026年7月23日公開）です。v1系は1.20.11（2025年1月20日）を最後に更新が止まっており、新規案件でv1を選ぶ理由はありません。2.18.0はRBAC（ロールベースアクセス制御）を含めてMITライセンスですが、2026年8月11日に開発ブランチのライセンスが改定され、RBAC関連のコードは今後のリリースでEnterprise扱いになります。ホスティングは公式のMedusa Cloudが月額29ドルから、流通総額に対する手数料は全プラン0.0%。自前運用も可能で、開発環境の要件はNode.js v20以上とPostgreSQLです。

日本で導入する場合の最大の障壁は決済です。公式の決済プロバイダはStripeのみで、コンビニ払いや代引きに対応する国内決済代行のプラグインはnpm上に見当たりません。既存のv1環境からの移行はデータベースに互換性がなく、商品以外は移行スクリプトの自作が前提になります。

Medusaの現在地｜v2.18系への到達とv1の実質停止

まず押さえるべきは、資料に「Medusa v2.0」と書かれている情報の多くがすでに古いという点です。v2.0.0の公開は2024年10月22日で、そこから約1年10か月のあいだに2.0.0を含めて67本の安定版が出ました。2026年8月12日時点の最新は2.18.0（2026年7月23日公開）。@medusajs/medusa、@medusajs/framework、@medusajs/js-sdk、@medusajs/admin-sdkはすべて同一バージョンで揃えて公開される設計です。

リリース間隔とv1系の最終更新日

2026年1月から8月11日までの安定版は23本、月あたり約3.3本です。内訳は均一ではありません。マイナー版に限ると2.13.0（1月22日）から2.18.0（7月23日）まで6本で、2月と3月はゼロ、6月は2本と偏っています。「月1回」を前提に保守枠を固定すると、集中した月に追随が遅れます。パッチ込みで月3本前後を見ておいてください。

一方でv1系は1.20.11（2025年1月20日）が最後のリリースで、19か月にわたり新しい版が出ていません。リポジトリ本体には2026年8月11日にもコミットが入っていますが、その開発線はすべてv2に向いています。v1で構築済みの環境は、機能追加もセキュリティ修正も期待できない状態です。

2026年8月のライセンス改定とRBACの版境界

ライセンスは、調べる時期によって答えが変わる状態にあります。バージョンで区切ってください。

RBACは@medusajs/rbacとして2.12.5（2026年1月9日公開）から同梱され、v2.18.0タグのLICENSEは1,075バイトの素のMITです。npm上の@medusajs/rbac 2.18.0のlicenseフィールドもMITと記載されています。つまり現在インストールできる版のRBACは追加費用なしで使えます。既定では無効で、v2.18.0のpackages/medusa/src/feature-flags/rbac.tsはdefault_valがfalse、環境変数MEDUSA_FF_RBACで有効化する設定です。

変わったのは2026年8月11日です。開発ブランチに「chore: update license」（PR #16110）がマージされ、ENTERPRISE-LICENSE.mdで特定されたEnterprise Edition materialsをMITの対象外とする但し書きがLICENSEに入りました。名指しされているのがRBACで、packages/modules/rbac/など複数のパスが列挙され、MedusaJS, Inc.との商用契約なしには使用・改変・配布ができないと定めています。同文書は「Enterprise機能フラグを有効化する行為は、有効な商用契約を保有しているという表明にあたる」とまで書いています。

ただし遡及しない旨の条項があり、既にMITで付与された旧版の権利は撤回されないと明記されています。判断軸はこうです。RBACを使うなら、2.18.0系に固定するか、2.19.0以降へ追随する時点で商用契約の要否を再確認する。追随を止めればセキュリティ修正も止まるので、権限管理が必須要件の案件は商用契約の見積もりを先に取ってください。

なおGitHubのスターは約3.5万、フォーク5,061、未クローズのIssueは42件、オープンPRは85件です（2026年8月12日時点）。GitHub APIのopen_issues_countはPR込みの合計値（127）を返すため、活性の判断では分けて数えてください。

4層構成で追うMedusaのリクエスト処理

Medusaの内部構造は、公式ドキュメントのアーキテクチャ解説で4つの層として説明されています。リクエストが通る順序は、API Routes、Workflows、Modules、データストアです。

API RoutesからPostgreSQLまでの経路

Modulesはドメイン単位で分かれた独立パッケージで、v1でプラグインとして個別導入していた領域の多くがv2では標準同梱になりました。データベースについて公式は「Medusa only supports PostgreSQL as the underlying database」と明記しています。MySQLやMongoDBを本体のデータストアに据える構成は取れません（カスタムモジュール経由での併用は可能です）。

補償関数によるロールバックの実測

v2で最も実務に効く変更がWorkflowsです。各ステップに補償関数を書いておくと、後続ステップが失敗したときに完了済みステップが逆順に取り消されます。在庫を引き当てた直後に決済が落ちる典型的な事故を、自前のtry-catchなしで戻せます。

// src/workflows/place-order.ts
import {
  createStep,
  createWorkflow,
  StepResponse,
  WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"

type PlaceOrderInput = { variantId: string; quantity: number }

const reserveInventoryStep = createStep(
  "reserve-inventory",
  async (input: PlaceOrderInput) => {
    const reservationId = `res_${input.variantId}`
    console.log("在庫を引き当てました:", reservationId, input.quantity)
    return new StepResponse({ reservationId }, { reservationId })
  },
  async (compensateInput) => {
    if (!compensateInput) {
      return
    }
    console.log("在庫引き当てを取り消しました:", compensateInput.reservationId)
  }
)

const capturePaymentStep = createStep("capture-payment", async () => {
  throw new Error("カード与信に失敗しました")
})

export const placeOrderWorkflow = createWorkflow(
  "place-order",
  (input: PlaceOrderInput) => {
    const reservation = reserveInventoryStep(input)
    capturePaymentStep()
    return new WorkflowResponse(reservation)
  }
)

上のファイルはワークフローを定義しただけなので、実行するには呼び出し側が要ります。

// src/run.ts
import { placeOrderWorkflow } from "./workflows/place-order"

placeOrderWorkflow()
  .run({ input: { variantId: "var_01", quantity: 2 } })
  .catch((e) => {
    console.log("ワークフローは失敗しました:", e.message)
  })

この2ファイルをNode.js v26.5.0上の@medusajs/framework 2.18.0でnpx tsx src/run.tsとして実行すると、出力は次の3行になります。

在庫を引き当てました: res_var_01 2
在庫引き当てを取り消しました: res_var_01
ワークフローは失敗しました: カード与信に失敗しました

1行目と2行目がワークフロー自身の出力で、3行目は呼び出し側のcatchによるものです。決済ステップが例外を投げた時点で、在庫引き当ての補償関数が自動的に呼ばれました。createStepの第2引数が本処理、第3引数が補償処理。StepResponseの第2引数に渡した値が、そのまま補償関数の入力になります。この分離のおかげで、外部API連携の巻き戻しをワークフロー定義の中に閉じ込められます。

CRM・ERP・CMSの代替として使えるかの線引き

MedusaはCRMやERPの代わりになるのか。結論から言えば、注文と顧客まわりは代替できる一方、会計や在庫原価まで踏み込む用途では不足します。役割ごとに線を引いていきます。

顧客管理をCRM代替に据える場合の限界

Medusaは顧客・顧客グループ・注文履歴をモジュールとして持ち、すべてAdmin APIから取得できます。購入履歴に基づくセグメント配信程度なら、外部のメール配信サービスと繋ぐだけで済むでしょう。足りないのは商談管理・案件パイプライン・営業活動ログ。BtoBで見積から受注までを追うなら、SalesforceなどのCRMを別に置き、Medusaを受注実行基盤として接続する構成になります。接続パターンの考え方はShopifyとSalesforceのAPI連携でできることが参考になります。

OMS・ERP用途で不足する在庫原価と会計連携

注文管理システム（OMS）としての利用は、Medusaの得意領域に近い部類です。複数販売チャネルの注文を一元化し、Fulfillmentモジュールで出荷を管理できます。ただしERPに期待される仕入原価の管理、棚卸資産の評価、仕訳の自動生成、債権債務の消込は本体に存在しません。在庫は「数量」として持つが「金額」としては持たない、と考えるとズレが少なくなります。会計連携が必要なら、注文確定イベントを購読するサブスクライバを書いて会計システムのAPIへ流す実装が前提です。

商品説明をヘッドレスCMSへ逃がす構成の使い分け

MedusaはCMSではありません。商品タイトル・説明・メタデータは持ちますが、記事コンテンツやランディングページ、多言語のリッチテキスト管理には向きません。特集ページやブランドストーリーを運用するなら、コンテンツ側は専用のヘッドレスCMSに置き、商品IDで突き合わせる構成が扱いやすくなります。Next.jsとの統合まで含めた選定基準はPayload CMSとNext.js統合の解説にまとめています。

日本のECで先に潰すべき実装差分

ここが国内記事でほとんど触れられていない部分です。要件定義の前に確認しておかないと、開発の後半で手戻りになります。

公式決済プロバイダの範囲と手動決済プレースホルダ

公式ドキュメントのPayment Module Provider一覧に載っているのはStripeだけです。加えて、Payment Moduleが標準で持つプレースホルダ用プロバイダ（識別子はpp_system）があります。これは決済処理を行わず加盟店側の手作業に委ねるもので、公式は代引き（cash-on-delivery）に近い挙動だと説明しています。

npmレジストリを「medusa」と各決済代行名の組み合わせで検索しても、KOMOJU、GMOペイメントゲートウェイ、PAY.JP、Veritrans、UnivaPayに対応するプロバイダは見つかりませんでした。出てくるのはStripe、PayPal（サードパーティ製）、Braintree、Mollieといった海外向けです。コンビニ払い、キャリア決済、後払いを扱う日本のECなら、AbstractPaymentProviderを継承した自作プロバイダの開発工数を最初から見積もりに入れてください。この一点だけでSaaS型を選ぶ判断も合理的です。Shopifyなら国内決済は標準で揃います。

円建て価格の保存形式と主要単位での整数管理

価格の保存形式はv1から変わりました。公式のPricingモジュール解説はamountプロパティについて「It’s stored as an integer in major units. For example, $20.00 is stored as 20, and $20.5 is stored as 20.5.」と書いています。最小単位（セント）ではなく主要単位（ドル）で持つということです。

日本円は小数を持たない通貨なので、1,980円は1980としてそのまま保存されます。StripeのAPIも日本円をゼロ小数通貨として扱い1980で受け取るため、単位系は一致。一見安全ですが、ドル建てとの混在ストアやv1からの金額データ移行では100倍のズレが入り込みます。移行スクリプトでは通貨ごとに換算の有無を分岐させてください。

消費税と軽減税率を割り当てる税リージョン設定

消費税はTaxモジュールのTax Regionで設定します。国コード単位で地域を作り、既定税率と条件付きの上書き税率を持たせる仕組みです。軽減税率が絡む食品ECでは、商品タイプ（Product Type）または商品単位の上書き税率で8%と10%を切り分けます。上書きルールが指せる対象は商品・商品タイプ・配送オプションの3種で、商品カテゴリは対象外です。国の下に州や県レベルのサブ税リージョンも作れます。税計算をロジックごと差し替えたい場合は、カスタムのTax Providerを実装できます。

管理画面の日本語カバー率96.7%という実測

管理画面（Medusa Admin）には日本語UIが同梱されています。v2.18.0タグのja.jsonをen.jsonと突き合わせたところ、英語側2,400キーのうち2,321キーが存在し、カバー率は96.7%、キーごと欠けているのは79件でした（キーの有無で算出しています）。欠けているのはレイアウトのカスタマイズ関連など、新しく追加された項目に偏っています。運用担当者に触ってもらう水準には達しており、日本語化そのものが導入の障壁になることはありません。

Medusa Cloudと自前運用の費用構造

Medusaは自前ホスティングのほかに、公式マネージドのMedusa Cloudという選択肢を持ちます。どちらを取るかで運用負荷が大きく変わります。

Medusa Cloudの月額とGMV手数料

注目すべきはGMV手数料が全プラン0.0%である点です。SaaS型ECでは流通総額に対する手数料が売上拡大とともに効いてきますが、Medusa Cloudは「No GMV-tax or special licenses」と明記し、インフラ費用のみの課金体系を取っています。注文数・商品数・販売チャネル数・地域と通貨の数はすべて無制限です。

ただし月額は「From」表記で、超過分は従量課金です。エッジリクエストはDevelopが月100万件、Launchが500万件、Scaleが1,000万件まで含まれ、超過分は100万リクエストあたり0.3ドルが加算されます。前章のRBACはEnterpriseプランの機能として掲載されており、8月11日のライセンス改定と方向が一致しています。

自前運用を選んだ場合に増える作業

開発環境ならNode.js v20以上とPostgreSQLだけで動きますが、本番はそうもいきません。イベントバス・ワークフローエンジン・ロック・キャッシュの実体としてRedisを置く構成が既定になります。そのうえで継続作業がのしかかります。月3本前後のバージョン追随、PostgreSQLのバックアップと復旧テスト、管理画面のビルド成果物の配信、ゼロダウンタイム更新の仕組みづくり。Scaleプランの299ドルは、これを人件費に換算すれば安い水準です。社内にNode.jsの運用経験があるかどうかが分岐点になります。

最小構成の立ち上げ手順とNodeのバージョン制約

検証環境の構築自体は数分で終わります。前提はGit、Node.js v20以上、起動中のPostgreSQLの3つです。

npx create-medusa-app@latest my-medusa-store

実行するとNext.jsのスターターストアフロントを同梱するか聞かれ、medusa-my-medusa-storeという名前のデータベースが自動作成されます。create-medusa-appも本体と揃って2.18.0が最新です。

落とし穴はNodeのバージョンです。公式Installationは本体を「v20+ (LTS versions only)」とし、Next.jsスターターストアフロントを入れる場合は「Node v24 LTS or lower」と条件を追加しています。Node 25以降は公式のサポート対象外。厄介なのは、Medusa本体のpackage.jsonのenginesがnodeを>=20とだけ指定して上限を縛っておらず、パッケージマネージャが警告を出さない点です。nvmなどでプロジェクト単位にv24以下を固定してください。

Medusaを選ぶべきでない場面

次のいずれかに当てはまるなら、Medusaは見送るべきです。

まず、v1で構築済みの環境をそのまま持ち上げたい場合。公式は「your existing database will not be compatible with the database for your v2 project」と明言しています。ORMがTypeORMからMikroORMへ変わり、データベース構造が刷新されたためです。公式が案内する移行経路は、商品を管理画面からエクスポートしてv2側でインポートする方法だけで、顧客・注文・割引などその他のデータは自作スクリプトで移すことになります。事実上の作り直しです。v1のプラグインも、PayPal、Klarna、Meilisearch、Strapi、Shopify、Brightpearlなどは代替の提供がなく、自作かガイドを見ながらの再実装になります。

次に、社内にNode.jsとTypeScriptを日常的に書けるエンジニアがいない場合。Medusaはノーコードの管理画面ではなくフレームワークです。カスタムのワークフロー、モジュール、決済プロバイダを書く前提で設計されており、コードを書かない運用は想定されていません。国内決済への対応は自作が必要なので、実装体制のないままの採用は失敗します。

そして、要件がSaaS型ECの標準機能で足りる場合。国内決済、配送会社連携、在庫管理、定型的なマーケティング機能をそのまま使えるなら、Medusaを選ぶ理由は薄いでしょう。Medusaの価値は、独自の受注フローや基幹システムとの深い連携といった、SaaSのカスタマイズ上限にぶつかる要件で初めて回収できます。この場合はSaaS型が正解で、当社もShopifyでのECサイト構築を選択肢として案内しています。ヘッドレス構成そのものの向き不向きはヘッドレスコマースの仕組みと導入判断へ、TypeScript製の対抗馬とどちらを取るか迷う段階ならVendureとMedusa JSの違いを比較した記事へ進んでください。

よくある質問

Medusaの最新バージョンはいくつですか？

2026年8月12日時点の最新は2.18.0（2026年7月23日公開）です。npmの@medusajs/medusaのlatestタグ、またはGitHubのリリース一覧が一次ソースになります。更新は月3本前後のペースなので、着手時点で必ず確認し直してください。

MedusaはMySQLやMongoDBでも動きますか？

本体のデータストアとしては動きません。公式ドキュメントは「Medusa only supports PostgreSQL as the underlying database」と明記しています。ただしカスタムモジュールを作れば、そのモジュール内で別のデータベースに接続できます。商品検索用の索引をMongoDBに置き、注文や在庫はPostgreSQLで扱うといった併用構成なら成立します。既存資産がMySQLだけの環境では、PostgreSQLの運用体制を用意するところから計画してください。

Medusa Cloudを使わず自社サーバーで運用できますか？

できます。MITライセンスの範囲でソースコードを取得し、Node.js v20以上とPostgreSQLが動く環境であれば自由にホスティングできます。本番ではイベントバス・ワークフローエンジン・ロック・キャッシュの実体としてRedisを併設する構成が既定です。注意点はRBACの版境界で、2.18.0まではMITですが、2026年8月11日のライセンス改定以降のリリースではEnterprise扱いになります。権限管理が必要な案件は、追随するバージョンを決める段階で商用契約の要否を確認してください。

Medusa v1からv2へアップグレードできますか？

コードもデータベースも引き継げないため、実質的な作り直しになります。移行に必要な作業は「Medusaを選ぶべきでない場面」で詳しく挙げました。v1環境を動かし続ける判断をする場合は、最終リリースが1.20.11（2025年1月20日）で19か月にわたり更新が止まっており、セキュリティ修正も出ていない点をリスクとして評価してください。

MedusaでECを構築する場合の開発期間はどれくらいですか？

公式に標準期間の提示はなく、実装が必要な範囲で決まります。スターターを使い、決済をStripeだけで済ませ、ストアフロントのデザイン調整に留めるなら小規模で収まります。国内決済代行への対応や基幹システムとの受注連携が加わると、決済プロバイダの自作だけでも別途工数が乗ります。見積の精度を上げるには、決済手段の一覧、外部連携先、権限要件（RBACの要否）を先に確定させてください。

関連記事

• ヘッドレスコマースとは？仕組み・メリット・主要プラットフォームと導入判断【2026年最新】
• VendureとMedusa JSの違いを比較｜TypeScript製ヘッドレスコマースの選び方【2026年最新】
• Payload CMSとは？使い方・Next.js統合・Strapiとの違いを解説
• ShopifyとSalesforceのAPI連携でできること：統合のメリットと活用法