Medusa v1.3.1: PriceList API, Promotions API, Migrations, And More!

Keep reading below to learn more about the new features, current work in progress, and what features we have planned for the futureMedusa v1.3.1: PriceList API, Promotions API, Migrations, And More!

Earlier this month we released version 1.3.0 with many new features, then followed it up by version 1.3.1 this week for some fixes and enhancements.

The new updates provide many new features and enhancements including an advanced Promotions API, a PriceList API, an addition to our suite of strategies to automatically fetch prices based on different parameters such as customer or region, and more!

We’ve also introduced a lot of new documentation pages and features to make your experience developing with Medusa even better.

Keep reading below to learn more about the new features, current work in progress, and what features we have planned for the future 🔍


PriceList API

In these new updates, we focused on strengthening our APIs to provide users and developers with more capabilities, especially related to product pricing.

Previously, the different variant prices of a product were handled using the MoneyAmount model. It presented a limitation when it came to advanced pricing use cases. For example, when a merchant wants to set the price based on the quantity of the product in the customer’s cart. This feature was not available before.

To add more customization capabilities, we’ve now introduced a new model PriceList. This model connects all the different models that can affect the pricing of a product with the MoneyAmount model.

Now, MoneyAmount belongs to PriceList in a one-to-many relationship. MoneyAmount also includes new fields such as min_quantity and max-quantity which, as explained earlier, can be used to specify the price of the product based on its quantity in the cart.

This change comes, of course, with a new interface in our Admin that allows creating and editing price lists with many handy configurations.

Along with adding the new model a new repository and service PriceListService has been added. The PriceListService allows retrieving, listing, modifying, and deleting price lists among other functionalities.

Also, the method setCurrencyPrice in the ProductVariantService has been removed to make sure that price lists can only be modified through the ProductListService.

Promotions API

Previously, Medusa had standard promotion features that most ecommerce platforms have. That includes multiple types of discounts such as percentage or free shipping discounts, applying discounts on either line items in an order or to the order total as a whole, discount scheduling and usage limits, and more.

In this new version, we’ve advanced our Promotions API even further to expand the use cases that Medusa supports. For example, a merchant might want to apply discounts for their VIP customers. Another example is applying discounts for a specified period of time.

This new implementation introduces a new model DiscountCondition. This model holds the conditions that determine whether a discount can be applied or not. It has relations to product type, tags, collections, and customer groups which are also introduced with this new release.

DiscountCondition belongs to DiscountRule and it removes the need for a direct relationship between DiscountRule and Product.

We’ve also added new endpoints for creating, updating, and removing discount conditions directly. This aims to provide developers with more ease of usage as it eliminates the need to use multiple different APIs to achieve the same functionalities.

This API will also open the doors for providing better integration with third-party discount services and tools for even more powerful features.


With the addition of the features mentioned above, it’s important to implement a good strategy to retrieve the correct price list of a product based on the context. The context can depend on different conditions including the region, currency, and customer group.

So, we’ve added a new strategy PriceSelectionStrategy that contains one method calculateVariantPrice. This method receives the variant and a context object and returns the original_price which is determined based on the region and currency provided in the context, calculated_price which is the lowest available price in this context, and prices which is an array of price lists.

This method is used when retrieving the price list of a product and its variants throughout Medusa including when retrieving a specific product or a list of products and when the cart is updated with more items.


With these new features, we’ve introduced 2 Migration scripts that are necessary to run after Medusa’s upgrade. Not running these migrations will cause inconsistencies and unexpected behaviors in your Medusa server.

To learn more about the migration scripts and how to run them check out the upgrade guide for version 1.3.0.

Line Item Adjustments

This new version of Medusa allows store operators to adjust line items in an order or a swap which provides more customization capabilities.

It introduces a new model LineItemAdjustment which gives more flexibility to adjust the pricing of line items in a cart, order, or swap. A discount can be added, removed, or modified and the price will reflect on the total calculation of the cart, order, or swap.

This also optimizes the calculation of totals, as it is no longer necessary to calculate the discounts every time the totals are retrieved.

The migration script added will go through your list of existing orders and add line item adjustments for each of the line items in the order.

Advanced Discount Conditions

To ensure your old discount rules play well with the new Promotions API explained earlier, this version includes a migration script that will go through your existing discount rules, create discount conditions for these rules, and move the former direct relationship between discount rules and products to become between discount conditions and products.

Base Entity

We’ve added in this new version 2 abstract classes BaseEntity and SoftDeletableEntity. New entities in Medusa are recommended to extend one of these 2 interfaces moving forward.

The BaseEntity class adds to any entity that extends it the 3 common columns id, created_at, and updated_at.

The SoftDeletableEntity class extends BaseEntity and adds an additional column deleted_at. This class should be used when you create entities that can be “soft deleted” instead of permanently deleted.

Moreover, a new utility function generateEntityId has been added to the core. It allows developers to generate IDs for their custom entities based on Medusa’s conventions.

This addition to the core allows developers customizing Medusa to seamlessly add new entities into Medusa.

Clean Up

As part of our update to the Medusa Admin, we’ve cleaned it up to remove all unused dependencies and components.

We also have changed how environment variables are loaded on the Medusa server. Previously, environment variables were loaded from the .env file at the root of the Medusa server.

This new update removes automatically loading environment variables from the .env file and allow developers to have freedom in how they load their environment variables.

If you want to make sure your server loads environment variables from the .env file after the new update, check out the upgrade guide to learn more about how to do that.


We’ve been growing our documentation at Medusa to include more guides and information about Medusa’s server, storefronts, and admin. These documentation pages give you an overview of Medusa’s architecture and how to customize or add your own functionalities.

We’ve also added some new features to enhance your experience while browsing our documentation.

Here are some of the documents and features we’ve added:

New API References

We’re excited to announce two new features in our documentation: the Services Reference and the Events Reference.

Services can be used in any of your custom endpoints, services, and subscribers. The service reference gives developers a better understanding of what services are available to use and what are some of their methods.

The event's reference shows developers what events they can listen to in subscribers, when they are triggered, and what data payload can be expected along with the event.


We’ve added new documentation pages to further explain the different components of Medusa’s shipping architecture including the Shipping Profile, Shipping Option, and Shipping Method. We’ve also added documentation to guide you in creating your own Fulfillment Provider.


We’ve added new documentation pages to give an overview of Medusa’s payment architecture and its different components. We’ve also added documentation to guide you in creating your own Payment Provider.


We are expanding our integrations documentation to include guides on how to integrate certain plugins into Medusa for different functionalities. These guides will help you understand everything you need to know about the plugin, what you can do with it, and how you can integrate the plugin into Medusa’s different components.

Some of the integrations we’ve added or improved are Stripe for Payment, SendGrid for Notifications, Slack for a bot that sends you new order notifications, MailChimp for newsletters, and more.

Support Both NPM and Yarn

You can now view CLI commands in both NPM and Yarn. Your preference is synchronized across the documentation which makes it easier for you to use the package manager of your preference while going through our documentation.

Dark Mode

We’ve added dark mode into both the documentation and the API reference! You can now browse our documentation without straining your eyes.

Work in Progress

While we are excited about our new release, we still have a lot of ideas and work to do to keep improving Medusa even more. Here are some new features we are currently working on:

Bulk Import/Export API

This new feature will give users using Medusa the ability to export their store’s data or import them. The process will be asynchronous to ensure that it does not affect the client, regardless of how big or small the data is. Exported files will be available for download at any point after they are generated, and the download of these files is protected.

At the moment we’re working on supporting CSV and Excel files, however, we’re looking into an implementation that would potentially accept supporting multiple formats in the future such as JSON.

You can read more about this feature in our discussion on GitHub.

Advanced Next.js Starter

We’re working on a new Next.js starter with a cleaner design and more advanced features. This new starter will allow developers to enable or disable features just by changing the store configurations.

Some of the features that will be added and are available to be switched on or off include search using the MeiliSearch plugin; customer accounts with the ability to make changes to their profiles and accounts such as change addresses and see order history; customer self-service returns and exchange; multi-regional support, and more!

Planned: Sales Channel API

We also have some features we are planning to work on later this year. One feature is the Sales Channel API. Its main purpose is to allow merchants to sell across multiple channels such as websites, mobile apps, or Amazon marketplace.

Although some of this is achievable at the moment, there’s no apparent difference between the different channels. All channels are viewed as a single sales channel. The Sales Channel API will make it possible to differentiate between the channels and ultimately provide certain rules or conditions based on the channel.

The Sales channels will first primarily focus on products and orders. Then, in the future, it will expand to include more Medusa resources.

Did you miss out on?

Person photo
Shahed NasserJun. 2, 20227 min.

Want to know more about Medusa

Find related blog posts below


Building with Nuxt.js for a Vue Ecommerce Platform Part 3: Ecommerce Checkout Flow with Stripe

In this guide, you will learn how to integrate and use Stripe as a payment provider in Medusa and Nuxt.js.


Online Marketplace Tutorial Part 3: Implement User Management and Permissions

This part of the tutorial focuses on user management within a store in a marketplace.


Which Frontend Framework You Should Pick for Your Ecommerce Storefront?

This article introduces you to the most efficient frontend frameworks that you can use to build an ecommerce storefront


Receive the most important updates around Medusa and our ecosystem