---
title: "Medusa knowledge base"
description: "Short answers to specific questions about building on Medusa."
url: https://medusajs.com/kb
last_updated: 2026-10-29T06:55:50Z
---

# Medusa knowledge base

Short answers to specific questions about building on Medusa.

Every entry is also available as Markdown: append `.md` to its URL. [llms.txt](https://medusajs.com/kb/llms.txt) lists every entry with a one-line answer.

## [Agentic commerce](https://medusajs.com/kb/agentic-commerce.md)

- [ACP vs UCP vs AP2 vs MCP: agentic commerce protocols explained](https://medusajs.com/kb/agentic-commerce/agentic-commerce-protocols.md): ACP (OpenAI and Stripe) covers the product feed, checkout, and delegated payment for ChatGPT. UCP (Google, with Shopify and other retailers) covers catalog, checkout, and orders for Google AI Mode and Gemini. AP2 proves payment authorization. MCP connects AI apps to tools. Medusa has an official ACP guide; UCP and AP2 are custom.
- [Best ecommerce backend for building AI shopping agents](https://medusajs.com/kb/agentic-commerce/backend-for-ai-shopping-agents.md): The best ecommerce backend for AI shopping agents exposes full cart and checkout through an API, lets you add your own agent endpoints, and supports search by meaning. Medusa fits teams that want to own that logic: its Store API covers cart to order, custom API routes add agent tools, and an official guide implements OpenAI's Agentic Commerce Protocol.
- [How to build an AI shopping assistant on your product catalog](https://medusajs.com/kb/agentic-commerce/build-ai-shopping-assistant.md): To build an AI shopping assistant on your product catalog, combine a retrieval layer that searches products by meaning, an LLM that writes the answer, and tools that read products and manage the cart. With Medusa, Medusa Search handles semantic retrieval, Store API routes act as the tools, and a custom API route connects them to your model.
- [Ecommerce platforms with MCP servers](https://medusajs.com/kb/agentic-commerce/ecommerce-mcp-servers.md): Medusa, Shopify, commercetools, and BigCommerce all publish MCP servers. Medusa offers a Docs MCP server for coding agents and the Medusa MCP server, which gives AI tools read-only access to Medusa Cloud store data, custom API routes, and deployment logs. Shopify, commercetools, and BigCommerce each ship docs servers plus servers for catalog, cart, or store management.
- [Easiest ecommerce stack to build with AI coding tools](https://medusajs.com/kb/agentic-commerce/ecommerce-stack-for-ai-coding.md): The easiest ecommerce stack to build with AI coding tools gives the AI tested commerce building blocks instead of asking it to write carts, tax, and orders from scratch. Medusa is one such stack: an open-source commerce framework with Agent Skills, a Docs MCP server, a one-prompt setup guide for coding agents, and Medusa Cloud hosting from $29/month.
- [How to make your product catalog visible to AI assistants](https://medusajs.com/kb/agentic-commerce/product-feeds-for-ai-agents.md): To make products visible in ChatGPT, send OpenAI a product feed that follows its Agentic Commerce Protocol schema: nine required fields per variant, uploaded as a full snapshot at least daily. Add schema.org Product markup and agent-readable pages for other assistants. Medusa has an official guide that builds the feed with a workflow and scheduled job.
- [How to let ChatGPT and other AI agents buy from your store](https://medusajs.com/kb/agentic-commerce/sell-through-ai-agents.md): To let ChatGPT buy from a custom store, implement OpenAI's Agentic Commerce Protocol (ACP): a product feed, checkout session endpoints, delegated payment, and order webhooks. Google AI Mode and Gemini use UCP with AP2 instead. Medusa has an official ACP guide with example code; UCP and AP2 are custom work today.

## [B2B commerce](https://medusajs.com/kb/b2b.md)

- [B2B company accounts, buyer roles and approval workflows](https://medusajs.com/kb/b2b/b2b-company-accounts-approvals.md): Medusa handles B2B company accounts through the official B2B Starter. A Company module groups employees, each linked to a customer with a spending limit and an admin flag. An Approval module requires company admin or sales manager approval before checkout. Value-based or multi-level approval rules are custom, built with workflow hooks.
- [How to build a B2B store with custom pricing per customer](https://medusajs.com/kb/b2b/b2b-customer-specific-pricing.md): To build a B2B store with custom pricing per customer in Medusa, put each customer or company in a customer group and attach a price list with a customer.groups.id rule. Add quantity tiers with min_quantity, and fetch live prices from your ERP at add-to-cart when the ERP owns contract prices. All of this runs on Medusa's open-source Pricing Module.
- [B2B ecommerce platform with quotes, company accounts and approval flows](https://medusajs.com/kb/b2b/b2b-ecommerce-platform.md): Medusa supports B2B ecommerce with quotes, company accounts and approval flows through its official B2B Starter, built on native price lists, tiered pricing, and sales channels. Companies, employees, spending limits, approvals, and quotes ship as open-source modules you can change. Punchout, requisition lists, net terms, and multi-level approval rules are custom work.
- [Net terms, purchase orders and bulk ordering for B2B](https://medusajs.com/kb/b2b/b2b-payment-terms-bulk-ordering.md): Medusa supports B2B net terms through its built-in system payment provider or a custom payment provider that authorizes now and captures when the invoice is paid. PO numbers fit in cart metadata, which Medusa copies to the order. The Medusa B2B starter adds bulk add-to-cart and per-employee spending limits, and company credit limits are a custom validation hook.
- [B2B quotes and RFQ: how quote-to-order works](https://medusajs.com/kb/b2b/b2b-quotes-rfq.md): In Medusa, B2B quotes work through a Quote module from the official B2B Starter and quote management guide. A customer requests a quote from the cart, the merchant edits prices and quantities on a draft order in Medusa Admin, and the customer accepts or rejects. Accepting converts the draft order into a regular order.
- [Shopify B2B alternatives for teams that can write code](https://medusajs.com/kb/b2b/shopify-b2b-alternatives.md): For teams that can write code, the main Shopify B2B alternatives are Medusa, BigCommerce B2B, OroCommerce, Adobe Commerce B2B and Vendure. Medusa's core is open source (MIT) with no GMV fee, and its B2B starter adds companies, approvals and quotes. Shopify B2B limits non-Plus plans to 3 catalogs and reserves per-company catalogs for Shopify Plus.

## [Build vs buy](https://medusajs.com/kb/build-vs-buy.md)

- [The true cost of Shopify apps vs owning your stack](https://medusajs.com/kb/build-vs-buy/shopify-app-costs-vs-owning-stack.md): Paid Shopify app plans for subscriptions, reviews, loyalty, bundles, and B2B run from $15 to $599 per month each, and some add per-transaction fees. Owning your stack with Medusa replaces those apps with modules you build once, guided by official tutorials, on Medusa Cloud from $29 per month with a 0% GMV fee. Developer time is the trade-off.
- [Should I use Shopify or build a custom store?](https://medusajs.com/kb/build-vs-buy/shopify-vs-custom-store.md): Use Shopify if you have no developer, a standard catalog, and need to sell fast. Build on a commerce framework like Medusa when your edge is custom product logic, subscriptions without per-transaction app fees, owned data, or AI features. Medusa Cloud starts at $29 per month with a 0% GMV fee; developer time is the main extra cost.
- [What does headless commerce actually mean?](https://medusajs.com/kb/build-vs-buy/what-is-headless-commerce.md): Headless commerce means your storefront is a separate app that talks to a commerce backend through an API. The backend handles products, carts, orders, and payments; you build and host the frontend. Medusa is an open source headless platform with a Store API and a Next.js Starter Storefront, so you build the frontend, not commerce itself.

## [Digital products](https://medusajs.com/kb/digital-products.md)

- [How do I sell digital and physical products in one checkout?](https://medusajs.com/kb/digital-products/digital-and-physical-products-one-checkout.md): Medusa sells digital templates and physical prints in one cart and one order. Prints use a shipping profile and carrier rates; digital items get a separate digital shipping option. Medusa's Digital Products tutorial then fulfills only the digital items after checkout and emails secure download links, while prints go through normal fulfillment.
- [How to add license keys and secure download links](https://medusajs.com/kb/digital-products/license-keys-download-links.md): Medusa has no built-in license keys or course gating, but you can build them. Store paid files privately with the S3 File Module Provider, issue presigned links that expire after download_file_duration, generate keys in a custom module from an order.placed subscriber, and revoke them from an order.canceled subscriber.
- [Merchant of record or your own store for digital products?](https://medusajs.com/kb/digital-products/merchant-of-record-vs-own-store.md): Use a merchant of record like Lemon Squeezy or Paddle if you sell only digital goods and want them to own sales tax and VAT for 5% + 50¢ per sale. Run your own store on Medusa when you sell physical items too, need custom delivery, or want lower fees and your own customer data, and handle tax filing yourself.

## [ERP integration](https://medusajs.com/kb/erp-integration.md)

- [Integrate Microsoft Dynamics 365 Business Central with Medusa](https://medusajs.com/kb/erp-integration/business-central.md): Medusa has no first-party Business Central connector, so you build one as a custom Medusa module that calls the Business Central API v2.0. Orders push to Business Central sales orders from an order.placed subscriber with rollback, Business Central webhooks drive order status updates, and scheduled jobs sync stock and customer prices into Medusa.
- [Which ecommerce platform is easiest to integrate with an ERP?](https://medusajs.com/kb/erp-integration/ecommerce-erp-integration.md): ERP integration is least painful when it runs inside the commerce engine. Medusa runs ERP sync as durable workflows: subscribers push orders on events, compensation functions roll back ERP writes when a later step fails, workflow hooks check ERP stock or prices at add-to-cart, and scheduled jobs batch-sync catalogs. Medusa has no prebuilt Business Central, NetSuite or SAP connector.
- [How to integrate NetSuite with Medusa](https://medusajs.com/kb/erp-integration/netsuite.md): Medusa has no prebuilt NetSuite connector. You build a custom Medusa module that calls NetSuite's SuiteTalk REST web services or RESTlets, then sync orders, items, stock, and prices with Medusa workflows, subscribers, and scheduled jobs. Workflows roll back NetSuite writes when a step fails, and NetSuite user event scripts can push changes to Medusa.
- [How to integrate Odoo with Medusa](https://medusajs.com/kb/erp-integration/odoo.md): Medusa has an official guide for integrating Odoo. It builds a custom Medusa module that authenticates with Odoo's external API and syncs products into Medusa with a workflow and a daily scheduled job. You extend it with the Medusa ERP recipe's patterns for orders, prices, and stock. On Odoo 19 and later, prefer the JSON-2 API.
- [How to integrate SAP Business One with Medusa](https://medusajs.com/kb/erp-integration/sap-business-one.md): Medusa has no prebuilt SAP Business One connector. You build a custom Medusa module that calls the SAP Business One Service Layer, an OData API, then sync items, stock, prices, business partners, and orders with Medusa workflows, subscribers, and scheduled jobs. From 10.0 FP 2602, Service Layer webhooks can push SAP changes to Medusa.

## [Headless storefronts and checkout](https://medusajs.com/kb/headless-checkout.md)

- [How to add a cart and checkout to an existing Next.js site](https://medusajs.com/kb/headless-checkout/add-ecommerce-to-nextjs.md): To add a cart and checkout to an existing Next.js site and keep your own design, connect it to a commerce backend such as Medusa. Medusa runs as a separate Node.js app with PostgreSQL, which Medusa Cloud hosts from $29/month. Your Next.js app calls it through the @medusajs/js-sdk package for carts, shipping, Stripe payments, and orders.
- [How to build a fully custom checkout flow](https://medusajs.com/kb/headless-checkout/custom-checkout-flow.md): To build a fully custom checkout flow, use a commerce backend whose checkout is an API rather than a hosted page. In Medusa, your storefront saves the email and addresses on the cart, sets a shipping method, starts a payment session such as Stripe, and completes the cart. Custom rules run in the completeCartWorkflow validate hook.
- [Stripe vs a commerce backend: what Stripe doesn't handle](https://medusajs.com/kb/headless-checkout/stripe-vs-commerce-backend.md): Stripe handles payments, not the rest of a store. With Stripe plus Postgres and Prisma, you build the cart, shipping, inventory, promotions, order lifecycle, returns, and admin yourself. Medusa is an open source commerce backend that ships those as modules and uses Stripe as its payment provider, so you keep Stripe and skip rebuilding order management.

## [International commerce](https://medusajs.com/kb/international-commerce.md)

- [Multi-currency pricing via API](https://medusajs.com/kb/international-commerce/multi-currency-pricing-api.md): Medusa handles multi-currency pricing through its Pricing Module: each variant has a price set with one price per currency, plus optional prices scoped by region, customer group or quantity. The Store API returns a calculated price for the shopper's region and country, with and without tax. Medusa does not convert currencies automatically.
- [How to sell in multiple countries from one ecommerce backend](https://medusajs.com/kb/international-commerce/multi-region-ecommerce.md): Medusa sells in multiple countries from one backend without running separate stores. You create a region per market with its own currency, countries and payment providers, set prices per currency or region, configure tax regions with tax-inclusive pricing for the UK and EU, and limit shipping options to service zones. Duties and automatic currency conversion need custom integrations.
- [Tax-inclusive vs tax-exclusive pricing for US, UK and EU](https://medusajs.com/kb/international-commerce/tax-inclusive-pricing-international.md): US stores usually show prices before sales tax and add tax at checkout, while UK and EU consumer prices include VAT. In Medusa, you enable tax-inclusive pricing per region or per currency, set VAT and sales tax rates in tax regions, and use the Avalara tax provider or a custom one for address-level rates.

## [Inventory and order management](https://medusajs.com/kb/order-management.md)

- [How do I manage inventory across multiple warehouses and sales channels?](https://medusajs.com/kb/order-management/multi-warehouse-inventory.md): Medusa is an open-source commerce platform that tracks stock per warehouse and store through its Inventory, Stock Location and Sales Channel modules. You create a location per site, link each sales channel to the locations it sells from, import SKUs and barcodes by CSV, and load stock levels. Transfers, purchasing and replenishment need custom code or an ERP.
- [How do I run online and in-store POS sales from one system?](https://medusajs.com/kb/order-management/online-and-retail-pos.md): Medusa runs online and in-store sales from one backend by giving each store's point of sale its own sales channel and stock location. A POS app places orders as draft orders through the Admin API, sharing products, customers, promotions and returns with the web store. Agilo's open-source POS Starter provides a ready app; terminals and offline mode need custom work.
- [Is there an open-source order management system I can extend?](https://medusajs.com/kb/order-management/open-source-oms.md): Yes. Medusa's MIT-licensed core is a commerce platform that works as an extensible open-source order management system. It natively handles multi-channel order capture, draft orders, order edits, returns, exchanges, claims, location-based stock reservation and fulfillment providers. You extend it with TypeScript workflows, subscribers and modules. Replenishment, purchasing and warehouse management need custom code or an ERP.

## [Marketplaces](https://medusajs.com/kb/marketplaces.md)

- [How do I build an artisan marketplace with AI coding help?](https://medusajs.com/kb/marketplaces/artisan-marketplace.md): To build a marketplace for local artisans with AI coding help, start from Mercur, a marketplace platform on Medusa. It gives each artisan a vendor panel, splits orders per seller, and pays sellers through Stripe Connect. Deploy it on Medusa Cloud, then customize it with an agent like Claude Code, which reads Mercur's bundled docs.
- [How do I build a multi-vendor marketplace with open source?](https://medusajs.com/kb/marketplaces/multi-vendor-marketplace.md): To build an open source multi-vendor marketplace on Medusa, either follow Medusa's marketplace recipe to add vendors and order splitting yourself, or start from Mercur, a marketplace platform on Medusa built by Rigby. Mercur ships seller onboarding, a vendor panel, commissions, split orders, Stripe Connect payouts, and reviews, and deploys on Medusa Cloud.
- [Build a peer-to-peer rental marketplace: build vs buy](https://medusajs.com/kb/marketplaces/rental-marketplace.md): For a peer-to-peer rental marketplace you can build from scratch, launch on Sharetribe, or start from Medusa with the Mercur marketplace platform. Mercur adds sellers, commissions, reviews and Stripe Connect payouts, and Medusa's rentals tutorial adds availability and per-day pricing. Deposits, insurance and payout timing are custom work.
- [Rental pricing, availability and security deposits](https://medusajs.com/kb/marketplaces/rental-pricing-availability-deposits.md): Medusa's official rentals tutorial prices a rental as the variant's daily price times the number of days, and blocks dates that overlap an existing pending or active rental. Hourly pricing and security deposits are custom. Deposits usually use a separate card authorization or a charge that you refund after the return.
- [How do Stripe Connect payouts work for a marketplace?](https://medusajs.com/kb/marketplaces/stripe-connect-marketplace-payouts.md): Stripe Connect pays marketplace sellers by charging the customer, transferring each seller's share to their connected account, and paying out to their bank on a schedule. For multi-seller carts, Stripe's docs point to separate charges and transfers. On Medusa, Mercur's Stripe Connect package handles seller onboarding and transfers after commission; you decide when payouts run.

## [Migrations and platform comparisons](https://medusajs.com/kb/migrations-and-platforms.md)

- [Composable commerce platforms for mid-market brands](https://medusajs.com/kb/migrations-and-platforms/composable-commerce.md): Composable commerce splits catalog, pricing, cart, orders, and other capabilities into independent parts connected through APIs. Medusa is an open-source composable commerce platform: each domain is an isolated Commerce Module you can extend, replace, or run in a Node.js app. It is free to self-host, and Medusa Cloud starts at $29/month with a 0% GMV fee.
- [Cheapest way to run a production ecommerce backend](https://medusajs.com/kb/migrations-and-platforms/ecommerce-backend-cost.md): Self-hosting open-source Medusa is the lowest cash cost: Medusa has no license or GMV fee, and a DigitalOcean setup runs about $29 to $59 per month as of October 2026. You pay instead in engineering time for backups, monitoring, and upgrades. Medusa Cloud starts at $29/month, with Launch at $99 for production stores.
- [How to migrate from Magento to a TypeScript stack](https://medusajs.com/kb/migrations-and-platforms/magento-migration.md): To migrate from Magento to Medusa, move catalog data first with Medusa's Docs MCP migration tool or its Magento plugin tutorial, then customers, orders, extensions, storefront, and 301 redirects. Medusa is TypeScript on Node.js. Customer passwords don't transfer, so customers set new ones, and saved cards move only through your payment provider.
- [Medusa vs Saleor](https://medusajs.com/kb/migrations-and-platforms/medusa-vs-saleor.md): Medusa and Saleor are both open-source headless commerce platforms on PostgreSQL. Medusa is TypeScript with REST APIs, and you extend it with modules and workflows inside the application. Saleor is Python and Django with a GraphQL-only API, extended through apps that run as separate services. Choose Saleor for GraphQL-first teams, Medusa for TypeScript teams.
- [Medusa vs Vendure](https://medusajs.com/kb/migrations-and-platforms/medusa-vs-vendure.md): Medusa and Vendure are both open-source TypeScript commerce platforms on Node.js. Medusa uses REST APIs, modules and workflows under an MIT license (except Enterprise RBAC and SSO), with Medusa Cloud generally available. Vendure uses NestJS, GraphQL APIs and plugins under GPLv3 or a commercial license, with Vendure Cloud not yet available. Choose Vendure for GraphQL, Medusa for REST.
- [Best open-source ecommerce platforms (2026), compared](https://medusajs.com/kb/migrations-and-platforms/open-source-ecommerce-platforms.md): The leading open-source ecommerce platforms in 2026 are Medusa, Saleor, Vendure, WooCommerce, Magento Open Source, PrestaShop, Sylius and Spree. Medusa fits TypeScript teams building custom commerce logic over REST APIs. Saleor and Vendure fit GraphQL-first teams. WooCommerce, Magento, PrestaShop and Sylius fit PHP teams, and Spree fits Ruby on Rails teams.
- [Outgrown Shopify Plus: what sits between Shopify and a custom build?](https://medusajs.com/kb/migrations-and-platforms/outgrown-shopify-plus.md): Medusa is the in-between option for brands that outgrew Shopify Plus: an open-source commerce framework, not a build from scratch. It ships carts, orders, pricing, payments, and an admin, and you add custom logic in TypeScript with workflows, workflow hooks, custom modules, and API routes, without Shopify Functions limits or a sandboxed checkout.
- [Switching from WooCommerce to a JavaScript stack](https://medusajs.com/kb/migrations-and-platforms/woocommerce-migration.md): To switch from WooCommerce to a JavaScript stack, move your catalog into Medusa, a TypeScript commerce backend on Node.js, with the WooCommerce guide in Medusa's Docs MCP migration tool. It migrates products, variants, prices, images, inventory, and categories. Then import customers, connect a storefront to the Store API, and add 301 redirects.

## [Subscriptions](https://medusajs.com/kb/subscriptions.md)

- [Coffee subscriptions without Shopify app fees](https://medusajs.com/kb/subscriptions/coffee-subscription-store.md): A roastery can run coffee subscriptions on Medusa with no subscription app fee. At $20,000 a month, Shopify Basic plus Recharge Starter costs about $519 a month in plan and app fees, versus $99 on Medusa Cloud Launch with a 0% GMV fee. The trade-off is building subscription logic from Medusa's official guide.
- [How to sell subscriptions and one-time products in one store](https://medusajs.com/kb/subscriptions/subscriptions-and-one-time-products.md): Medusa has no built-in Subscription Module, but its official Subscriptions guide shows how to add one: a custom module, a daily scheduled job that creates and charges renewal orders, and admin pages. One-time products use the standard checkout. Mixing both in one cart, dunning, and pause, skip, or swap are custom work.

## [Tickets and bookings](https://medusajs.com/kb/tickets-and-bookings.md)

- [How to build a booking or reservation system on an ecommerce platform](https://medusajs.com/kb/tickets-and-bookings/bookings-and-reservations.md): To build bookings on Medusa, pick a pattern first: event tickets, date-range rentals, pre-orders, or time-slot appointments. Medusa has official tutorials for tickets, rentals and pre-orders, built as custom modules linked to its products, carts and orders. Double bookings are prevented with add-to-cart checks, inventory reservations and workflow locks.
- [Sell event tickets and merch on one site without Eventbrite fees](https://medusajs.com/kb/tickets-and-bookings/sell-tickets-and-merch.md): Medusa lets you sell event tickets and merch from your own store with no per-ticket platform fee, so you pay only your payment provider. Its official ticket booking tutorial covers venues, seat maps, show dates, QR tickets and check-in. Seat limits use native inventory and discount codes use the native Promotion Module.