---
title: "Medusa v2でEC構築する判断基準｜構成・費用・ライセンスと日本の決済対応【2026年11月】"
url: "https://www.issoh.co.jp/column/details/4372/"
published: 2024-11-29
updated: 2026-11-03
categories: ["EC"]
publisher: "株式会社一創"
---

# Medusa v2でEC構築する判断基準｜構成・費用・ライセンスと日本の決済対応【2026年11月】

Medusa（メデューサ）は、Node.jsとTypeScriptで書かれたオープンソースのコマースエンジンです。カート・注文・在庫などのEC機能をAPIとして提供し、画面は自由に作るヘッドレス型で、ShopifyやEC-CUBEの代替候補として検討されます。この記事では2026年11月3日時点のnpmレジストリ・GitHub・公式ドキュメントをもとに、最新版の構成、ライセンスの境界、費用、日本で実装が詰まる箇所を数値で示し、Medusaを選ぶべきかどうかを判断できるようにします。

## まとめ

Medusaの最新版は2.22.2（2026年10月30日公開）です。v1系は1.20.11（2025年1月20日）を最後に止まっており、新規案件の選択肢はv2だけです。本体はMITライセンスのままですが、2.19.0（2026年8月13日）からRBAC（ロールベースのアクセス制御）とSSO（シングルサインオン）がEnterprise扱いになり、使うにはMedusaJS社との商用契約が要ります。2.22.0からはNode.js v22.22.0以上が必須です。

日本で導入するときの最大の障壁は決済です。公式の決済プロバイダはStripeと、2.22.2で加わったAdyen（beta）の2つで、Adyen側はカード・Apple Pay・Google Payに限られます。コンビニ払いや後払いを扱うなら決済プロバイダの自作が前提です。公式ホスティングのMedusa Cloudは月額29ドルからで、流通総額への手数料は全プランで0.0%です。

## Medusa v2の現在地｜2.22.2までの版とv1の停止

「Medusa v2.0」を前提にした解説は、もう実態と合いません。v2.0.0の公開は2024年10月22日で、2026年10月30日の2.22.2までに安定版は76本出ています。[npmの@medusajs/medusa](https://www.npmjs.com/package/@medusajs/medusa)のlatestタグが2.22.2を指し、`@medusajs/framework`や`create-medusa-app`も同じ番号で揃って公開されます。

### リリース頻度とv1系の最終版

2026年1月から10月30日までの安定版は32本、月に約3本です。マイナー版は2.13.0（1月22日）から2.22.0（10月21日）まで10本ありますが、2月と3月はゼロで、9月は2.20.0と2.21.0の2本が出ました。更新回数を固定するより、セキュリティ修正が出たときに影響を評価し、必要なら臨時で上げる手順を保守契約に入れておくほうが確実です。

v1系は1.20.11が最後で、21か月にわたり新しい版が出ていません。v1で構築した環境には機能追加もセキュリティ修正も届かないと考えてください。GitHubのスターは37,067、未クローズのIssueは80件、オープンPRは42件です（2026年11月3日、GitHub Search APIで集計）。

### 2.19.0からのライセンス境界（RBAC・SSO）

ライセンスは版で区切って判断します。npm上の`@medusajs/medusa`のlicense欄は2.18.0まで「MIT」、2.19.0から「SEE LICENSE IN LICENSE」に変わりました。[ENTERPRISE-LICENSE.md](https://github.com/medusajs/medusa/blob/develop/ENTERPRISE-LICENSE.md)はv2.18.0のタグには無く、v2.19.0以降のタグに含まれています。

同文書が名指しするEnterprise MaterialsはRBACとSSOです。RBACモジュール、権限チェックのミドルウェア、管理画面のロール・ポリシー画面、OIDC認証プロバイダ（`@medusajs/auth-oidc`）などのパスが列挙され、商用契約なしの使用・改変・配布は認められません。「Enterprise機能フラグを有効にする行為は、有効な商用契約を持っていることの表明になる」とも書かれています。一方、汎用の認証やユーザー・招待管理、ワークフロー基盤は対象外でMITのままです。

既に付与されたMITの権利は撤回しないという条項があるため、2.18.0以前のRBACはMITで使い続けられます。ただし旧版に留まる場合、セキュリティ修正の入手は保証されません。2.21.0のStore API強化では2.18.0〜2.19.0向けを含む旧版用パッチが配布されましたが、リリースノート自身が「通常は旧版にパッチを出さない」と断っており、例外的な扱いです。管理画面の権限分けやSSOが必須要件の案件は、要件定義の段階で商用契約の見積もりを取ってください。

## 2.19〜2.22へ上げるときに壊れる箇所

2026年8月以降の4つのマイナー版には、既存プロジェクトの動作を変える破壊的変更が入っています。[GitHubのリリースノート](https://github.com/medusajs/medusa/releases)で「Breaking change」と明記されたもののうち、ストアの表示や運用環境に直接響くものを挙げます。

### Node.js 22.22.0以上への引き上げ（2.22.0）

package.jsonのengines条件は、2.18.0の「>=20」から、2.19.0で「^20.19.0 || >=22.12.0」、2.22.0で「>=22.22.0」へと2段階で上がりました。リリースノートはNode.js 20のサポート終了を理由に挙げています。CI・本番コンテナ・開発者のローカルのそれぞれがこの条件を満たしているかを、2.22系へ上げる前に確認してください。1か所でもNode 20のまま残ると、その環境だけ動かなくなります。

### Store APIの返却フィールド制限（2.20.0・2.21.0）

2.20.0で、Store APIは1回のクエリで4階層以上の関係を展開するリクエストを400エラーで拒否するようになりました（商品系ルートだけは4階層まで許可）。2.21.0では各ルートの`allowed`リストが厳格化され、リストに完全一致しないフィールドはエラーにならず応答から黙って消えます。

後者が厄介です。自作のストアフロントが独自フィールド（ブランド名など）を取得していると、アップグレード後に画面の一部が空になるだけで、ログには何も出ません。リリースノートは`allowFields`ミドルウェアで許可を足し直す方法を示しています。上げる前に、ストアフロントが`fields`パラメータで要求している項目を洗い出しておくのが安全です。2.20.0ではメモリ上で動く検索プロバイダ`@medusajs/search-local`も削除され、`@medusajs/search-postgres`などへの切り替えが要ります。

### 管理画面のVite 7化とブラウザ要件（2.19.0）

2.19.0で管理画面はVite 7.3.6とReact Router 7.18.2に上がり、2.22.2ではViteが7.3.7になりました。プロジェクトに直接入れている`vite`と`react-router-dom`は、上げる先の版が指定する番号に合わせる必要があり、管理画面の対応ブラウザはChrome 107以上、Safari 16以上などに引き上げられています。店舗スタッフが古い端末で管理画面を開く運用なら、端末の更新も計画に入れてください。

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

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

### API RoutesからPostgreSQLまでの経路

| 層          | 役割            | 実体                 |
| ---------- | ------------- | ------------------ |
| API Routes | HTTPリクエストの受け口 | Express.js         |
| Workflows  | 業務ロジックの実行単位   | workflows-sdk      |
| Modules    | ドメインごとのデータ管理  | Cart・Payment・Taxほか |
| データストア     | 永続化           | PostgreSQL         |

Modulesはドメインごとに分かれた独立パッケージで、v1でプラグインとして個別に入れていた機能の多くがv2では標準で同梱されています。データベースはPostgreSQLだけが対象で、MySQLやMongoDBを本体のデータストアにはできません。

### 補償関数によるロールバックの実行結果

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.22.2の環境で`npx tsx src/run.ts`として実行した出力が次の3行です（2026年11月3日）。

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

決済失敗を模した例外によって、在庫引き当てステップの補償関数が呼ばれたことが分かります。この例の引き当てと取り消しはログ出力だけで、実際の在庫更新や決済APIへの接続はしていません。`createStep`の第2引数が本処理、第3引数が補償処理で、`StepResponse`の第2引数に渡した値がそのまま補償関数の入力になります。外部APIに対する取消や返金を補償関数として定義しておけるため、複数のシステムをまたぐ受注処理を1つのワークフローで設計できます。

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

注文と顧客まわりは任せられますが、会計・在庫原価・コンテンツ管理は別システムが要ります。

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

顧客・顧客グループ・注文履歴はモジュールとして持ち、Admin APIから取得できます。2.22.0では顧客データのCSVエクスポートも管理画面に加わりました。購入履歴による顧客の分類やメール配信も作れますが、分類ルールの実装と、Mailchimpなどの配信サービスとの連携は別途必要です。足りないのは商談管理や営業活動の記録で、BtoBで見積から受注までを追うならSalesforceなどのCRMを別に置き、Medusaを受注の実行基盤として接続します。接続の考え方は[ShopifyとSalesforceの連携方法｜連携アプリ2種の料金と自前開発の実装・API上限から決める同期設計](/column/details/2955/)が参考になります。

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

複数チャネルの注文の一元化と出荷管理は得意領域です。2.20.0からは在庫を小数で持てるようになり、重さや長さ単位の量り売りも扱えます。一方、仕入原価の管理、棚卸資産の評価、仕訳の生成、債権債務の消込は本体にありません。在庫は「数量」で持つが「金額」では持たないと考えると、期待とのズレが小さくなります。会計連携は注文確定イベントを購読するサブスクライバを書き、会計システムのAPIへ送る形になります。

### 商品説明をヘッドレスCMSへ逃がす構成

Medusaは商品タイトルと説明は持ちますが、特集ページやブランドストーリーのようなリッチなコンテンツ管理には向きません。コンテンツは専用のヘッドレスCMSに置き、商品IDで突き合わせる構成が扱いやすくなります。Next.jsとの組み合わせは[Payload CMSとは？使い方・Next.js統合・Strapiとの違いを解説【v3.90・4.0 beta】](/tech/details/8065/)で詳しく扱っています。

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

日本向けのECでは、決済手段・円建て価格・消費税・管理画面の日本語の4点を要件定義の前に確かめてください。後回しにすると開発の後半で手戻りになります。

### 公式決済プロバイダの対応範囲｜Stripe・Adyen（beta）

[公式のPayment Module Provider一覧](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider)に載っているのはStripeとAdyenの2つです。Adyenは2.22.2で追加されたbeta版で、対応はカード（3Dセキュア含む）・Apple Pay・Google Payに限られ、リダイレクトで完了する決済やWebhookで後から確定する非同期の決済は未対応と明記されています。また、初回の売上確定ではAdyen上で与信額の全額が確定され、その後の部分確定はMedusa側の記録だけになるため、分割出荷ごとに売上を確定したい案件には向きません。Stripe側も同梱されているのはカード等の基本サービスとBancontact・BLIK・iDEAL・OXXOなど欧州・中南米向けの決済手段で、コンビニ決済専用のサービスはありません。ほかに、決済処理をせず加盟店の手作業に任せるプレースホルダ（識別子`pp_system`）があり、公式は代引きに近い挙動と説明しています。

npmレジストリで「medusa」と国内決済代行名（KOMOJU・GMOペイメントゲートウェイ・PAY.JP・Veritrans・UnivaPay・PayPay）を組み合わせて検索しても、Medusa用のプロバイダは見つかりません（2026年11月3日）。コンビニ払い・キャリア決済・後払いを出すなら、`AbstractPaymentProvider`を継承した自作プロバイダの工数を最初から見積もりに入れてください。国内決済代行の接続方式は[GMOペイメントゲートウェイとは？強み・手数料の目安とPHPでのOpenAPI実装、他社比較](/column/details/17525/)、Adyenを国内の決済代行と併用する考え方は[Adyenとは？仕組み・料金体系と日本での使いどころ、国内決済代行との併用判断](/column/details/18348/)で整理しています。

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

[Pricingモジュールの解説](https://docs.medusajs.com/resources/commerce-modules/pricing/concepts)は、価格のamountを「stored as an integer in major units」とし、20ドルは20、20.5ドルは20.5で保存すると書いています。最小単位（セント）ではなく主要単位で持つ方式です。日本円は1,980円がそのまま1980になり、ゼロ小数通貨として1980を受け取るStripeとも単位が一致します。危ないのはドル建てとの混在ストアと、最小単位で持っていたv1からの金額データ移行で、[移行ガイド](https://docs.medusajs.com/learn/introduction/from-v1-to-v2)によればv1は10ドルを1000（セント）で保存していたため、移行時に米ドルは100で割り、日本円はそのまま移すといった通貨ごとの分岐が要ります。最小単位で金額を受け取る外部APIへ送るときは、逆向きの換算になります。

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

消費税はTax Regionで国単位の地域を作り、既定税率を持たせます。軽減税率が絡む食品ECでは、地域の既定を10%にし、商品または商品タイプ単位の上書き税率で8%を割り当てます。上書きできる対象は商品・商品タイプ・配送オプションの3種で、商品カテゴリ単位の指定はできません。カテゴリで税率を分けている既存ECから移るときは、対象商品に個別に上書き税率を設定するか、税率に対応する商品タイプへ整理し直すかを選びます。

### 管理画面の日本語訳の収録率

管理画面（Medusa Admin）には日本語UIが同梱されています。v2.22.2タグの`ja.json`を`en.json`と突き合わせると、英語側の2,457キーはすべて日本語側に存在しました。値が英語のまま残っているのは17キーで、JSONやCSVといった形式名、EAN・UPCなどのコード名、入力欄のプレースホルダです。2.18.0時点で欠けていた約80キーは埋まっています。ただしキーの有無で分かるのは訳の抜けまでで、訳語の適切さは分からないため、店舗スタッフが使う画面は日本語UIで一通り確認してください。

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

自前ホスティングのほかに、公式のマネージド環境Medusa Cloudがあります。選び方で運用負荷が大きく変わります。

### Medusa Cloudの月額と従量課金

| プラン        | 月額      | エッジリクエスト/月 | 主な追加要素         | GMV手数料 |
| ---------- | ------- | ---------- | -------------- | ------ |
| Develop    | 29ドルから  | 100万       | GitHub連携デプロイ   | 0.0%   |
| Launch     | 99ドルから  | 500万       | オートスケール・独自ドメイン | 0.0%   |
| Scale      | 299ドルから | 1,000万     | バックグラウンドワーカー   | 0.0%   |
| Enterprise | 個別見積    | 個別         | RBAC・SSO・監査ログ  | 0.0%   |

[料金ページ](https://medusajs.com/pricing/)は「No GMV-tax or special licenses」と書き、注文数・商品数・販売チャネル数・地域と通貨はすべて無制限です。月額は「From」表記で、エッジリクエストは100万件あたり0.3ドル、データ転送は全プランで超過分が課金され、計算時間はLaunchとScaleが超過課金、Developは上限で打ち止め（Capped）です。RBACとSSOはEnterpriseの列にだけ載っており、2.19.0のライセンス変更と同じ線引きです。

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

開発環境はNode.jsとPostgreSQLだけで動きますが、本番は別です。公式はイベントモジュールとワークフローエンジンについて「In production, it’s recommended」としてRedis版を勧めており、ロックとキャッシュにもRedis版が用意されています。そのうえで、月3本前後の版への追随、前章の破壊的変更への対応、PostgreSQLのバックアップと復旧テスト、ゼロダウンタイム更新の仕組みづくりが継続的に発生します。インフラの運用を社内で担えないなら、Medusa Cloudが候補です。本番の開始はLaunch（月99ドルから）、専用のバックグラウンドワーカーが要るならScale（月299ドルから）が目安になります。ただしCloudが引き受けるのはインフラまでで、自社コードの改修やアップグレード時の動作確認は残ります。

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

前提はGit、Node.js、起動中のPostgreSQLの3つです。

```
npx create-medusa-app@2.22.2 my-medusa-store
```

実行するとNext.jsのスターターストアフロントを入れるかを聞かれ、`medusa-my-medusa-store`という名前のデータベースが自動で作られます。

落とし穴はNodeの版です。[公式のInstallation](https://docs.medusajs.com/learn/installation)は本体に「Node.js v22.22.0+ (LTS versions only)」を求め、Next.jsスターターを入れる場合は「Node v24 LTS or lower」と条件を足しています。つまりスターター込みで公式要件を満たすのは、v22系の22.22.0以上か、v24系のLTSです。非LTSのv23系は含みません。enginesは下限しか縛っておらず、v25以降でもパッケージマネージャは警告を出しません。nvmやVoltaでプロジェクトごとに版を固定してください。

## Medusaを選ぶべきでない場面

次のどれかに当てはまるなら、Medusaは見送るのが妥当です。

1つ目は、v1の環境をそのまま持ち上げたい場合です。[公式の移行ガイド](https://docs.medusajs.com/learn/introduction/from-v1-to-v2)は「your existing database will not be compatible with the database for your v2 project」と明言しています。ORMがTypeORMからMikroORMへ変わりデータベース構造が刷新されたためで、公式が示すのは商品を管理画面でエクスポートしてv2側でインポートする方法だけです。顧客・注文・割引は自作スクリプトで移すことになり、事実上の作り直しです。

2つ目は、社内にNode.jsとTypeScriptを日常的に書けるエンジニアがいない場合です。Medusaはノーコードの管理ツールではなくフレームワークで、国内決済は自作が前提です。2.21.0の返却フィールド変更のように、アップグレードのたびにコード側の確認が要ります。

3つ目は、SaaS型ECの標準機能で要件が足りる場合です。国内決済・配送会社連携・定型的な販促がそのまま使えるなら、Medusaを選ぶ理由は薄いでしょう。独自の受注フローや基幹システムとの深い連携のように、SaaSのカスタマイズ上限にぶつかる要件があって初めて元が取れます。構築方式ごとの向き不向きは[ECサイトの構築・作り方を解説｜5つの方法の選び方と要件定義から公開までの手順](/column/details/12828/)で比較しています。Medusaでの受注基盤づくりや国内決済プロバイダの自作を外部に任せたい場合は、当社の[ECシステム開発](/service/system/ec/)でも対応しています。

## よくある質問

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

2026年11月3日時点の最新は2.22.2（2026年10月30日公開）です。npmの`@medusajs/medusa`のlatestタグか、GitHubのリリース一覧で確認できます。2026年は月に約3本のペースで出ているため、着手時点で必ず確認し直してください。

### Medusaは無料で商用利用できますか？

本体はMITライセンスで、商用でも無料で使えます。例外はRBACとSSOで、2.19.0以降はEnterprise Materialsとして商用契約が必要です。2.18.0以前の版に含まれるRBACはMITのまま使えます。ただし旧版向けのセキュリティパッチは2.21.0のような例外を除いて出ないため、固定する場合は修正の提供状況を個別に追う必要があります。

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

本体のデータストアとしては動かず、PostgreSQLが必須です。カスタムモジュールを作れば、そのモジュールの中で別のデータベースに接続できます。既存資産がMySQLだけの環境では、PostgreSQLの運用体制を用意するところから計画してください。

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

データベースもコードも引き継げないため、実質的な作り直しです。公式の移行手段は商品のエクスポートとインポートだけで、顧客や注文は自作スクリプトで移します。v1を動かし続ける場合は、1.20.11（2025年1月20日）以降セキュリティ修正が出ていない点をリスクとして評価してください。

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

できます。Node.js v22.22.0以上とPostgreSQLが動く環境なら自由にホスティングでき、本番ではRedisの併設が公式の推奨です。ホスティング先を自社にしてもRBACとSSOのライセンス条件は変わらないので、権限管理が要る案件は商用契約の要否を先に確認してください。

## 関連記事

- [ヘッドレスコマースとは？仕組み・従来型ECとの違いと主要基盤の比較、導入判断【2026年10月】](/column/details/1326/)
- [VendureとMedusaの違い｜Vendure 3.7とMedusa 2.21をライセンス・API・B2Bで比較【2026年10月】](/tech/details/1500/)
- [Adyenとは？仕組み・料金体系と日本での使いどころ、国内決済代行との併用判断](/column/details/18348/)
- [GMOペイメントゲートウェイとは？強み・手数料の目安とPHPでのOpenAPI実装、他社比較](/column/details/17525/)
- [Payload CMSとは？使い方・Next.js統合・Strapiとの違いを解説【v3.90・4.0 beta】](/tech/details/8065/)

---

出典: [Medusa v2でEC構築する判断基準｜構成・費用・ライセンスと日本の決済対応【2026年11月】](<https://www.issoh.co.jp/column/details/4372/>)（株式会社一創）
