This article introduces Medusa, an open-source, developer-focused alternative to Shopify that allows for customization and scaling as needed.
Shopify is an ecommerce platform that provides merchants with an easy and quick way to set up their online store. It’s a popular choice among businesses who don’t want the technical complexity of other platforms when creating their online store.
However, it’s well known that Shopify has limits to its scalability and that trying to build more custom logic into it can be a dreadful experience for developers.
Medusa is an open-source Shopify alternative that was built to solve some of these scaling problems.
Out of the box, Medusa provides similar core ecommerce functionalities as Shopify, but its open and composable architecture allows for more flexibility and a better developer flow when building custom logic or integration with third-party services.
This article covers Medusa’s advantages over Shopify and how to get started using Medusa.
Let’s take a closer look at what Medusa offers to developers.
A developer-focused platform
Medusa is built for developers, and its main focus is providing a great developer experience. It’s built with abstraction layers that make it highly extendible if any customization is needed.
Adding integrations is also hassle free due to its headless and abstract architecture. Developers don’t need to worry about using workarounds to make the platform work with other services and tools. They can extend the existing abstract layers to create any integration.
As a developer-focused Shopify alternative, Medusa provides detailed documentation that’s constantly being improved to allow developers to build their ecommerce platform following simple steps.
Medusa’s headless architecture
Headless is the concept of decoupling the frontend from the backend. For the backend, this means that it’s free from the shackles of any presentation layer. The backend is only responsible for handling the data and logic of the system.
The backend exposes a set of APIs that allows any frontend or presentation layer to interact with it.
This decoupling gives developers the freedom to choose which language or framework to use for the frontend. Developers can use Jamstack frameworks like Gatsby and Next.js. They can also integrate different types of channels such as mobile apps or marketplaces.
Medusa is composed of three components: the headless server, the storefront, and the admin panel. Although Medusa provides two starter storefronts — one built with Next.js and another with Gatsby, and an intuitively-designed admin panel — developers have the full freedom to build these components with any other frameworks from scratch. All they need to do is interact with the REST APIs.
This allows the developers working on the frontend to focus their efforts on providing a unique and good user experience without the storefront being tightly knit to the backend.
An open-source Shopify alternative
A big disadvantage of proprietary solutions is that you’ll never have full ownership of your tech stack. No matter how many customization capabilities you’re given, you’ll always be limited in your choices of functionalities or tools.
An open-source solution like Medusa, on the other hand, allows you to have full ownership of your tech stack. You can use Medusa as is for your ecommerce store, but you can also completely customize the core and adapt it to any specific need.
This flexibility guarantees that businesses can have a platform that completely caters to their use case. Additionally, their platform can grow with their business needs with time.
Whether they need to add more features and customizations in the future or ensure that the platform can scale with them over time, this can be done with Medusa with no limitations.
Flexibility for developers and merchants
The flexibility that the advantages above lead to means that both developers and merchants have full freedom in their choice of services and tools to use within their Medusa ecommerce platform.
For example, for rich CMS functionalities, merchants can choose to integrate Strapi, Contentful, or any other service they want.
There are no restrictions on what tools or services can be used. This is even more important when choosing local payment and fulfillment providers.
All integrations are accomplished through plugins. You can either choose from ready-made plugins or create your own.
Plugins are installed on your Medusa server in a plug-and-play manner. They run within the same process as the Medusa server, so you don’t need to allocate extra server space or infrastructure.
Advanced Ecommerce Features
Putting aside all technical advantages, Medusa also comes with many advanced ecommerce features out of the box, including the following.
A big problem that Shopify businesses run into is supporting multiple currencies in their store. This feature requires special conditions depending on what country you operate in or what plan you have.
However, even with this feature enabled, it still doesn’t provide businesses with the flexibility to format and set pricing per product.
The lack of availability of this feature and its limitations lead businesses to set up and manage multiple stores for each currency. This causes a lot of extra manual work and human errors.
Medusa, on the other hand, provides multi-region support out of the box, and without limitations. You can add as many regions as you want, specify the currency for these regions, and manage the pricing of each product for each currency individually all from the same admin dashboard.
This eliminates the need for the extra manual work that comes with managing multiple stores and prevents human errors that occur with it.
Automated RMA (return merchandise authorization) flows
According to statistics by UPS, 73% of shoppers say their return experience affects whether they purchase again from the retailer in the future or not. So, it’s essential to provide your ecommerce store with an easy and hassle-free return experience.
Medusa provides fully automated return, swap and claim processes that can easily be handled from the Admin dashboard — starting from the customer’s request to return the items from the storefront to the items being marked as returned.
Items can also be swapped or exchanged in the same manner. This will also be automatically reflected on the integrated accounting systems and can all be managed easily from the admin dashboard.
Promotions APIs and gift cards
Medusa provides an advanced Promotions API with many customization capabilities. Merchants have the standard use cases from this promotions API that you’d find on all platforms — such as setting free shipping discounts, fixed-amount discounts, or discount percentages.
Additionally, merchants can specify discounts specific to customer groups, products, number of redemptions, and much more conditions.
Furthermore, gift cards can easily be added and managed into Medusa through the admin dashboard, and they’re handled differently from other products on purchase. Gift cards also have their own advanced conditions and customizable settings that can be specified from the admin dashboard.
There’s a growing need for platforms that enable the creation of online marketplace ecommerce platforms. Medusa’s extensibility makes it a great platform to create your online marketplace.
A community plugin called Medusa Extender makes this even easier to achieve. This plugin gives you even more customization capabilities to fully extend the core and modify it for a marketplace use case.
Medusa also has a tutorial series that introduces the basics of creating a marketplace — including linking different entities like users and products to stores, managing orders per store and globally, and managing users within their store and their permissions.
Medusa comes with many APIs and ecommerce features that provide developers and merchants with advanced functionalities.
The Tax API, apart from the settings it provides out of the box, is implemented with abstraction to allow integrating third-party services and tools to handle advanced taxes.
The PriceList API provides many pricing conditions for products related to discounts, customer groups, and more.
All these settings and functionalities available in the headless server can be easily managed from the intuitive admin dashboard built with Gatsby.
Medusa is also working on more features such as bulk import and export of products, sales channels, multi-warehouse support, and more.
Community and support
As a developer-focused platform and as an open-source solution, Medusa is focused on working closely with the community and providing any support needed.
Developers can join Medusa’s community on Discord, where they can join in discussions, showcase their work with Medusa, and get help whenever they run into trouble while using Medusa.
Developers can get help from the community and from the core Medusa team almost instantly. All they have to do is ask a question on the
#need-help channel and someone will guide them through the solution — often within a few hours.
Developers can also report bugs, contribute to Medusa, and join discussions on the GitHub repository.
How to Get Started with Medusa
This section gives a general overview of how to install a Medusa server, the Medusa admin, and the Gatsby Storefront.
To use Medusa, you need Node.js with at least version 14 installed.
How to set up a Medusa server
Start by installing the Medusa CLI tool:
npm install -g @medusajs/medusa-cli
Then, run the following command to create a new Medusa server:
medusa new my-medusa-store --seed
This installs the Medusa server in the
my-medusa-store directory, which is also created. The
--seed option creates and seeds an SQLite database in the
Finally, change to the directory of the Medusa server and start the server:
The server runs on port
9000 by default. You can test it out using the REST APIs, or you can follow along with the rest of this section and see it in action when connected to the Medusa admin and storefront.
It’s also recommended that you install a storage plugin to handle storing product images. You can use either MinIO, S3, or DigitalOcean Spaces.
How to install the Medusa admin
In a separate directory, run the following command to clone the Admin GitHub repository and change to the newly created directory:
git clone https://github.com/medusajs/admin medusa-admin
Then, install the dependencies with npm:
Finally, make sure that the Medusa server is still running and start the Medusa admin server:
The admin typically runs on
localhost:7000. Open it in your browser and you should see a login screen.
To log in, you can use the demo user credentials with the email
email@example.com and password
On the admin dashboard, you can add products, manage orders, manage store configurations, and much more.
How to install the Gatsby Storefront
Install the Gatsby CLI if you don’t have it installed:
npm install gatsby-cli -g
Then, in a different directory than the previous ones, run the following command to install the Gatsby storefront:
gatsby new my-medusa-storefront https://github.com/medusajs/gatsby-starter-medusa
Then, change to the newly created directory and rename
mv .env.template .env.development
Finally, while the Medusa server is still running, start the Gatsby server:
The storefront runs on port
localhost:8000 by default. Open that in your browser. You should see some demo products from the Medusa server. You can add those products to your cart, go through the checkout process and place an order. You can also create an account and check out customer profile features.
That’s it for this introduction to Medusa, a viable Shopify alternative for developers looking for more freedom and flexibility in setting up an ecommerce store.
After setting up your Medusa server, admin, and storefront, you can explore more of what you can do with Medusa, including:
Should you have any issues or questions related to Medusa, feel free to reach out to the Medusa team via Discord.