Desmond  Gerber

Desmond Gerber


How to Use Medusa to Build Customizable & Flexible Ecommerce Solutions

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.

Medusa’s Advantages

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

Medusa's 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.

Multi-currency support

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.

Multiple prices for each currency for a product

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

Discounts in Medusa

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.

Multi-vendor support

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.

Other features

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.

Taxes in Medusa

The PriceList API provides many pricing conditions for products related to discounts, customer groups, and more.

Price list in Medusa

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 my-medusa-store directory.

Finally, change to the directory of the Medusa server and start the server:

cd my-medusa-store
medusa develop

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 medusa-admin
cd medusa-admin

Then, install the dependencies with npm:

npm install

Finally, make sure that the Medusa server is still running and start the Medusa admin server:

npm start

The admin typically runs on localhost:7000. Open it in your browser and you should see a login screen.

Admin Login

To log in, you can use the demo user credentials with the email and password supersecret.

On the admin dashboard, you can add products, manage orders, manage store configurations, and much more.

Admin Dashboard

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

Then, change to the newly created directory and rename .env.template to .env.development:

cd my-medusa-storefront
mv .env.template .env.development

Finally, while the Medusa server is still running, start the Gatsby server:

npm start

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.

Gatsby Storefront

Next Steps

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.

Original article source at:

#medusa #ecommerce 

How to Use Medusa to Build Customizable & Flexible Ecommerce Solutions
Edward Jackson

Edward Jackson


Medusa: The Open-source Shopify Alternative ⚡️


Medusa is an open-source headless commerce engine that enables developers to create amazing digital commerce experiences.


  • Install Medusa CLI
npm install -g @medusajs/medusa-cli
  • Create a new Medusa project
medusa new my-medusa-store --seed
  • Start your Medusa engine
medusa develop
  • Use the API
curl localhost:9000/store/products | python -m json.tool

We have a prebuilt admin dashboard that you can use to configure and manage your store find it here: Medusa Admin

After these four steps and only a couple of minutes, you now have a complete commerce engine running locally. You may now explore the documentation to learn how to interact with the Medusa API. You may also add plugins to your Medusa store by specifying them in your medusa-config.js file.

Roadmap 2022

Write-ups for all features will be made available in Github discussions prior to starting the implementation process.


  •  Admin revamp
  •  Tax API
  •  Strategy pattern
  •  Promotions API
  •  Bulk import / export


  •  Extended Product API (custom fields, price lists, publishing control, and more)
  •  Extended Order API (managing placed orders, improved inventory control, and more)
  •  Sales Channel API
  •  Multi-warehouse support
  •  GraphQL API

Setting up a storefront for your Medusa project

Medusa is a headless commerce engine which means that it can be used for any type of digital commerce experience - you may use it as the backend for an app, a voice application, social commerce experiences or a traditional e-commerce website, you may even want to integrate Medusa into your own software to enable commerce functionality. All of these are use cases that Medusa supports - to learn more read the documentation or reach out.

To provide a quick way to get you started with a storefront install one of our traditional e-commerce starters:

npm install -g gatsby-cli
gatsby new my-medusa-storefront
npx create-next-app -e my-medusa-storefront

With your starter and your Medusa store running you can open http://localhost:8000 (for Gatsby) or http://localhost:3000 (for Nextjs) in your browser and view the products in your store, build a cart, add shipping details and pay and complete an order.


Medusa comes with a set of building blocks that allow you to create amazing digital commerce experiences, below is a list of some of the features that Medusa come with out of the box:

  • Headless: Medusa is a highly customizable commerce API which means that you may use any presentation layer such as a website, app, chatbots, etc.
  • Regions allow you to specify currencies, payment providers, shipping providers, tax rates and more for one or more countries for truly international sales.
  • Orders come with all the functionality necessary to perform powerful customer service operations with ease.
  • Carts allow customers to collect products for purchase, add shipping details and complete payments.
  • Products come with relevant fields for customs, stock keeping and sales. Medusa supports multiple options and unlimited variants.
  • Swaps allow customers to exchange products after purchase (e.g. for incorrect sizes). Accounting, payment and fulfillment plugins handle all the tedious work for you for automated customer service.
  • Claims can be created if customers experience problems with one of their products. Plugins make sure to automate sending out replacements, handling refunds and collecting valuable data for analysis.
  • Returns allow customers to send back products and can be configured to function in a 100% automated flow through accounting and payment plugins.
  • Fulfillment API makes it easy to integrate with any fulfillment provider by creating fulfillment plugins, check the /packages directory for a full list of plugins.
  • Payments API makes it easy to integrate with any payment provider by creating payment plugins, we already support Stripe, Paypal and Klarna.
  • Notification API allow integrations with email providers, chatbots, Slack channels, etc.
  • Customer Login to give customers a way of managing their data, viewing their orders and saving payment details.
  • Shipping Options & Profiles enable powerful rules for free shipping limits, multiple fulfillment methods and more.
  • Medusa's Plugin Architecture makes it intuitive and easy to manage your integrations, switch providers and grow with ease.
  • Customization is supported for those special use cases that all the other e-commerce platforms can't accommodate.

Database support

In production Medusa requires Postgres and Redis, but SQLite is supported for development and testing purposes. If you plan on using Medusa for a project it is recommended that you install Postgres and Redis on your dev machine.

To use Postgres and Redis you should provide a database_url and redis_url in your medusa-config.js.


Medusa is all about the community. Therefore, we would love for you to help us build the most robust and powerful commerce engine on the market. Whether it is fixing bugs, improving our documentation or simply spreading the word, please feel free to join in. Please check our contribution guide for further details about how to contribute.

Repository structure

The Medusa repository is a mono-repository managed using Lerna. Lerna allows us to have all Medusa packages in one place, and still distribute them as separate NPM packages.

Download Details: 
Author: medusajs
Source Code: 
License: MIT

#nodejs #ecommerce #headless #medusa #shopify #node #webdev

Medusa: The Open-source Shopify Alternative ⚡️