Building a generational company requires exceptional, hard-working people. 

We are tackling the complexities of commerce infrastructure that no one else has dared to.


## Change how commerce is built



small

Grid

Our core engineering team is responsible for building our orchestration tooling and core commerce modules. You will be critical to the long-term success of Medusa.


#### Software Engineer, Core



mb-1

Open Role card

Careers

<p class="text-regular font-medium text-theme-text-primary">
  Try Medusa
</p>
<p class="text-regular text-theme-text-secondary">
  Spin up your environment in a few minutes.
</p>



We care deeply about developer experience across all our products. Our primitives and tooling allow developers to effortlessly build digital commerce applications at record speed.

Today, we are excited to announce a massive update to our Subscriber API that significantly improves the developer experience of a core concept in Medusa’s customization toolbox.

## Subscribers

Services in Medusa emit events whenever actions like creating and updating records occur. Subscribers in Medusa provide a way for developers to run asynchronous logic in response to these events. This could include syncing a product to an external service when it is updated in Medusa or applying a special discount when a set of specific products is added to a cart.

With our updated API, you can create subscribers using a pattern similar to how you build API Routes.

```ts
// src/subscribers/order-placed.ts
export default async function ({ data, container }) {
	const { id } = data
	
	const slackService = container.resolve("slackService")
	const orderService = container.resolve("orderService")

	const order = await orderService.retrieve(id)

	await slackService.sendNotis({ data: order })
}

export const config: SubscriberConfig = {
  event: OrderService.Events.PLACED,
}
```

Example of a Subscriber

The example above illustrates a few key points of the updated Subscriber API:

*   Exports from files in `/subscribers` control the behavior of your event handlers. The default export is a function with the logic to run, and the `config` export specifies the event that logic should be run in response to

*   The handler accepts an argument of type `SubscriberArgs`. This can be de-structured to access the event data and the Medusa container.

In the example above, we register a handler that is run every time the product updated event is triggered.

The new approach to registering subscribers also comes with the benefit of making it easier than ever to set up a handler for multiple events. The `event` field in the config accepts either a single event or a list of events. Continuing with the above example, it would be possible to update the handler to update the external system when a product is created, updated, and deleted.

```ts
// src/subscribers/product-sync.ts
import { syncProductsWorkflow } from "../workflows"

export default async function ({ data, eventName, container }) {
  await syncProductsWorkflow.run({ input: data })
}

export const config: SubscriberConfig = {
  event: [
		ProductService.Events.CREATED,
		ProductService.Events.UPDATED,
		ProductService.Events.DELETED
	]
}
```

By updating the `event` field and adding a few additional lines of code, the handler can now process all relevant events. This keeps the external system synchronized with Medusa.

## What is next?

We are excited to hear your thoughts about our new Subscriber API. If you have any feedback or experience issues, don’t hesitate to post on our [GitHub Issues board ](https://github.com/medusajs/medusa/issues)or [GitHub Discussions](https://github.com/medusajs/medusa/discussions). To check other of our recent releases, check out our [Medusa Recap page](/recap/).

You can also track our progress on [X](https://twitter.com/medusajs) and in our [changelog](https://medusajs.com/changelog/).


Announcing Improved Subscriber API

Digital commerce happens across multiple systems, whether ERPs, CMSs, marketing tools, custom services, or other tools. A key challenge is to ensure these systems work together to complete the tasks that drive your business forward. We are, therefore, incredibly excited to announce the beta release of Medusa Workflows, a new, powerful primitive in the Medusa toolbox to help build custom business flows involving multiple systems.

Medusa’s Workflows SDK enables developers to write critical business flows with a simple DX and a strong foundation. Workflows have built-in retry and rollback mechanisms, which make them resilient to intermittent failures and a great place to define your commerce stack’s integrations and customizations.

Medusa Workflows are not dependent on Medusa’s commerce modules. You can start using them to integrate your commerce stack regardless of what ecommerce platform you are on, giving you access to Medusa’s powerful customization tools without needing to migrate your commerce platform.

## Build a Workflow

Building Workflows is like writing JavaScript functions, but unlike regular functions, the Workflows SDK creates an internal representation of your Workflow to keep track of its progress, retry failing steps, and roll back operations if necessary.

### Define a Workflow Step

To create a Workflow, you first define a Workflow Step using the Workflows SDK’s `createStep` function.

```ts
import { createStep, StepResponse } from "@medusajs/workflows-sdk"

const reserveInventory = createStep("reserve-inventory", async (cart, context) => {
    const inventoryService = context.container.resolve("inventoryService");
    await inventoryService.reserveInventory(cart.items);
    return new StepResponse({ success: true });
  }
);
```

The above step resolves an Inventory Service from the dependency injection container and reserves inventory for items in a Cart. Note that the step takes a Cart as input and responds with a StepResponse. The StepResponse can be used in subsequent steps.

### Create a Workflow

Once your step is created, you can use it within a Workflow. To construct a Workflow you use the `createWorkflow` helper from the Workflows SDK.

```ts
import { createStep, StepResponse, createWorkflow } from "@medusajs/workflows-sdk"

const reserveInventory = createStep("reserve-inventory", async (cart, context) => {
  const inventoryService = context.container.resolve("inventoryService");
  await inventoryService.reserveInventory(cart.items);
  return new StepResponse({ success: true });
});

const acceptQuoteWorkflow = createWorkflow("accept-quote", function (input) {
  const cart = retrieveCart(input.cartQuoteId);
  reserveInventory(cart);
  authorizePayment(cart);
  createOrder(cart);
});
```

The above Workflow accepts a quote shared with a customer, and the step we created to reserve inventory is used as part of the Workflow. In the Workflow, we have used our `reserveInventory` Workflow Step.

The function passed to `createWorkflow` is used to generate a representation of the Workflow logic and map the data dependencies between steps. For example, the Workflow SDK knows that `reserveInventory` step needs the output of `retrieveCart` as its input. This enables Medusa to automatically retry a step if it fails and only progress when possible and allowed. If a step fails more than a configurable number of times, Medusa will automatically roll back previous steps.

### Defining compensating actions

Let’s define the compensation for our `reserveInventory` step. We do this by specifying what data our step will need to roll back in the StepResponse and a compensation function to execute when rolling back.

```ts
import { createStep, StepResponse } from "@medusajs/workflows-sdk"

const reserveInventory = createStep("reserve-inventory", async (cart, context) => {
    const inventoryService = context.container.resolve("inventoryService");
    await inventoryService.reserveInventory(cart.items);
    return new StepResponse({ success: true }, cart.items);
  },
  async (items, context) => {
    const inventoryService = context.container.resolve("inventoryService");
    await inventoryService.releaseInventory(items);
  }
);
```

Note that the StepResponse now specifies the `cart.items` as rollback data. This is then used in the compensation function to release the inventory.

### Triggering a Workflow

You can execute a Workflow from different places within Medusa. For example, you may use API Routes if you want the workflow to execute in response to an API request or a webhook. Subscribers if you want to execute a workflow when an event is triggered. Or Scheduled Jobs if you want your workflow to execute regularly.

Here’s an example of executing a Workflow in an API Route. You can learn about more ways of triggering Workflows in our docs.

```ts
// src/api/quotes/accept/route.ts

import { acceptQuoteWorkflow } from "@/workflows"

export async function POST(req, res) {
  const workflow = acceptQuoteWorkflow(req.scope)

  await workflow.run({
    cartQuoteId: req.cart_id
  })

  res.json({ accepted: true })
}
```

## What can you use Workflows for?

Medusa Workflows are especially good for orchestrating multiple tools to achieve a task. Integrating systems in your stack using Workflows, for example, ensures that data is kept consistent and that unexpected errors are handled gracefully. To build an integration with Workflows, you would create a custom Medusa service connecting to your 3rd party system. The custom service can then be resolved in your steps to execute actions.

The more systems you integrate with Medusa, the more Workflows you can create to automate your operations and push your customer experience forward. Consider the example of integrating purchase orders from your ERP system with inbounds in your WMS system. With a Medusa connection to your ERP and WMS, you can easily map the purchase order flow and other ERP to WMS flows. Additionally, because you have other connections - like your product information - available, you can leverage those in your Workflows. For example, you can quickly configure your purchase order Workflow to record the expected restock date of your products to display to customers.

![](/images/Untitled%20\(8\)-65817d5b.png)

### Long-running workflows (coming soon)

With the initial beta release, Workflows can run exclusively in-band. We will soon add support for long-running Workflows that include asynchronous operations or human-in-the-loop steps. This opens further use cases for Workflows. For example, you can build a Workflow to manage the preparation of new products for sale. The Workflow starts when a product is inbounded at your warehouse. Then, tasks can kick off for taking pack shots, writing titles and descriptions, translating copy, and merchandizing the product. As each task is completed, the Workflow can proceed. All tasks would be mapped as Workflow Steps and could be completed in systems across your stack. If a task fails to complete or a configurable timeout is reached, rollback logic can help keep your data consistent, or notify responsible parties.

![](/images/long-running%20\(1\).png)

## Core Workflows

Workflows are a key part of our efforts toward shipping Medusa 2.0. With Medusa 2.0, we are decoupling most of Medusa’s internal services and bringing them to standalone packages available on npm. This means you can use Medusa’s services, like Products, Pricing, Carts, etc., independently from the rest of Medusa. We will continue to offer Medusa’s powerful and customizable commerce API in a way that’s easy to install with `npx create-medusa-app`. For each default API endpoint, there will be an available core Workflow to do things like creating products, adding to cart, applying discounts, and much, much more. The core Workflows will orchestrate Medusa (or custom) modules and be extensible. This does two things:

1.  It makes Medusa pluggable - you can use any provider to handle Products, Carts, Discounts, etc. The Workflow will call the provider when it needs to.

2.  You will get a new and easy way to extend business logic by injecting custom code into Workflows. There is no need to modify core services or override default endpoints; the Workflow will ensure your custom logic is called when required.

Core Workflows are introduced incrementally behind the `medusa_v2` feature flag, and more and more Workflows become available as we ship new Commerce Modules.

## What’s next?

The Workflows SDK joins Custom Entities, Services, API Routes, Subscribers, and Cron Jobs in the Medusa toolbox. With Workflows, Medusa provides a primitive for building custom business flows spanning multiple systems. It has built-in failure handling and rollback logic to ensure your critical Workflows run smoothly and your data is kept consistent. You can start using the Workflows SDK without migrating to Medusa’s commerce modules, making it an excellent tool for integrating your digital commerce stack and building customizations for customer experiences and internal operations.

Visit [our docs](https://docs.medusajs.com/development/workflows) to get started with Workflows. And follow us on [X](https://twitter.com/medusajs) to stay tuned for updates on Long Running Workflows and information about our Commerce Module releases as we prepare for [Medusa 2.0](/blog/toward-medusa-2/).


Announcing the Medusa Workflows SDK

We are excited to announce Medusa’s Pricing Module - a standalone pricing service that enables granular pricing configurations. The Pricing Module ships as an npm package that can be installed in any Node project requiring advanced pricing logic and is integrated into Medusa experimentally behind the `medusa_v2` feature flag as part of our efforts to [release Medusa 2.0](https://medusajs.com/blog/toward-medusa-2/).

In Medusa, the Pricing Module is used to set prices for Product Variants conditional on currencies, regions, customer groups, sales channels, and more. You can read more about the Pricing Module functionality [here](https://medusajs.com/pricing-module/). Now, the Pricing Module’s logic works entirely independently and can be used to configure prices for anything specific to your needs.

The Pricing Module has two key functionalities:

1.  Creating a set of prices for a resource with pricing rules governing when each is applicable.

2.  Choosing the correct price to use given a context.

## Using the Pricing Module

Imagine you want to differentiate the prices of tickets to a tech conference based on the customer’s location. You want to offer cheaper tickets to local companies. With the Pricing Module you first configure your pricing rules:

```ts
const myTicketPriceSet = await pricingModuleService.create({
  rules: [{ rule_attribute: "city" }],
  prices: [
    { amount: 1000, currency_code: "usd", rules: {} },
    { amount: 500, currency_code: "usd", rules: { city: "New York" } },
  ]
})
```

The above code returns a PriceSet to associate with your ticket.

The Pricing Module provides a `calculatePrices` function to get the correct price to charge a customer. Before calling the function you will collect the city your customer is in; for example, based on the IP address, and pass it as context `calculatePrices`.

```ts
const [priceToCharge] = await pricingModuleSerivce.calculatePrice(
	{ id: [priceSet.id] },
	{ context: { currency_code: "usd", city: "New York" } }
)

priceToCharge // { calculated_price: 500, currency_code: "usd" }
```

You can configure as many rules as you need, and the Pricing Module will always provide the correct price to your customer, considering things like overlapping applicability and rule priorities.

## Serverless support

The Pricing Module is ready for serverless environments, making it possible to run price calculations from tools like Lambda, Vercel, or Netlify Functions. To use the Pricing Module in a serverless function, initialize the Pricing Module with the initialize function.

```ts
// my-next-app/app/api/price/route.ts

import { initialize } from "@medusajs/pricing"
import { headers } from 'next/headers'

export async function GET(req, res) {
  const headers = headers()
  const ipCity = headers.get("x-vercel-ip-city")

  const pricingModule = await initialize({ /* db credentials here */ })
  const [price] = await pricingModule.calculatePrices(
		{ id: [priceId] }, 
		{ context: { currency_code: "usd", city: ipCity } }
	)

	res.json({ price: price.calculated_amount })
}
```

With serverless support you can offer your customers fast and highly personalized experiences.

## What’s next?

At Medusa, we build tools for developers to create custom digital commerce applications. The Pricing Module is another step toward preparing Medusa for version 2.0. [Read more about what’s to come here.](https://medusajs.com/blog/toward-medusa-2/)

Try the Pricing Module today by installing `@medusajs/pricing` from npm. For more details on how the Pricing Module works - including details about the Pricing Module’s Price List feature - visit our [docs](https://docs.medusajs.com/modules/price-lists). We are excited to hear your feedback.


Announcing Pricing Module

We are excited to announce a new Scheduled Jobs API that significantly improves the developer experience of a core concept in Medusa’s extensibility toolbox.

## Scheduled Jobs

Scheduled Jobs in Medusa is a feature that lets developers schedule tasks or cron jobs to automate repetitive tasks. For example, you can push daily updates to an external ERP system or generate weekly sales reports.

With the new Scheduled Jobs API, setting up recurring tasks can be achieved with only a few lines of code with a syntax that is familiar to any JavaScript developer.

```
// src/jobs/daily-erp-update.ts
import { ProductService, ScheduledJobsConfig, ScheduledJobsArgs } from "@medusajs/medusa"
import ErpService from "../services/erp"

export default async function ({ container }: ScheduledJobsArgs) {
	const productService: ProductService = container.resolve("productService")
	// Service for interacting with external ERP system
	const erpService: ErpService = container.resolve("erpService")
	
	const products = await productService.listAndCount()

	await erpService.update(products)
}

export const config: ScheduledJobsConfig = {
  name: "daily-erp-update",
	schedule: "0 0 * * *" // At 00:00 every night
}
```

The above example illustrates a few key points of how to use the new Scheduled Jobs API:

*   Exports from files in `/jobs` control the behavior of the action performed in your task. The default export is a function with the logic to run, and the config specifies the name and schedule of the task.

*   The handler is a function that gets invoked each time the job runs. In the given example, it lists products in Medusa and forwards them to the ERP system.

*   The config assigns a name to the job and sets the schedule for the job. In the provided example, the schedule is set to repeat the job every night at 00:00.

You can read more about the new API [in our documentation](https://docs.medusajs.com/development/scheduled-jobs/overview).

We are excited to hear your thoughts about our new Scheduled Jobs API. If you have any feedback or experience issues, don’t hesitate to post on our [GitHub Issues](https://github.com/medusajs/medusa/issues) board or [GitHub Discussions](https://github.com/medusajs/medusa/discussions).

Track our progress on [X](https://twitter.com/medusajs) and in our [changelog](https://medusajs.com/changelog/).


Announcing Scheduled Jobs API 

Medusa Next.js Starter Redesign Announcement thumbnail

The Medusa [Next.js Starter Template](https://medusajs.com/nextjs-commerce/) has been a popular starting point for Next.js developers working with Medusa. We thought it deserved some love, so the Starter just got a big update with a complete design overhaul, Medusa UI components, Next.js 14, and better product search.

The goal of the Starter is to provide a foundation for developers to build on. It consists of a fully functional ecommerce frontend, already connected to a Medusa backend. We aimed for a design that is fresh but neutral so you can easily customize it to fit your brand.

## Medusa UI Support

We redesigned the Starter to work with [Medusa UI](https://docs.medusajs.com/ui) components and icons. This results in a fresh, recognizable design language and components that allow for easy customization.

Medusa UI is a React implementation of the Medusa design system. The collection includes components, hooks, utility functions, icons, and [Tailwind CSS](https://tailwindcss.com/) classes. It's designed for building a consistent user interface across Medusa Admin and other Medusa applications.

## Ready for Medusa 2.0

While we [work toward Medusa 2.0](https://medusajs.com/blog/toward-medusa-2/), you can already try out some of our cutting-edge serverless modules with the Next.js Starter. The Starter has support for both the [Product](https://docs.medusajs.com/modules/products/serverless-module) and the Pricing module, as well as Remote Query to build your own serverless product endpoints. If you’re feeling adventurous, you can enable these experimental features by enabling the `MEDUSA_FF_MEDUSA_V2` feature flag in both the Starter and the server.

## New design showcase

### Home

The homepage has been cleaned up and now shows featured product collections.

![](/images/Screenshot%202023-11-23%20at%2009.43.56-12d8a5f8.jpg)

### Product detail page

The product detail page has a new layout and now uses Medusa UI components.

![](/images/Screenshot%202023-11-23%20at%2009.43.45.jpg)

### Product overview page

The product overview page has been redesigned and now features sorting out of the box.

![](/images/Screenshot%202023-11-23%20at%2009.45.30.jpg)

### Product search

The Starter already supported Algolia and MeiliSearch out of the box, but now has a revamped instant search UI and a server-rendered search results page.

![](/images/Screenshot%202023-11-23%20at%2009.46.41.jpg)

### Cart

The new cart design is built almost exclusively from Medusa UI components.

![](/images/Screenshot%202023-11-23%20at%2009.47.51.jpg)

### Checkout

The redesigned checkout process provides a streamlined experience, making it easier than ever for customers to finalize their purchases.

![](/images/Screenshot%202023-11-23%20at%2009.50.39.jpg)

### Get started with Next.js and Medusa

See the full new design in action in our [updated hosted demo](https://next.medusajs.com/).

Want to build with the Starter yourself? To get started, [clone the Medusa Next.js Starter Template from GitHub](https://github.com/medusajs/nextjs-starter-medusa).


Announcing Next.js Starter Redesign with Medusa UI support

Medusa is a set of tools for developers to create digital commerce applications. Often, these are e-commerce sites, but they can also be [marketplaces](https://medusajs.com/blog/foraged-custom-marketplace/), [enterprise OMS systems](https://medusajs.com/blog/makro-omnichannel-order-orchestration/), [B2B commerce platforms](https://medusajs.com/blog/visionary-b2b/), and much more. When we started Medusa, we wanted to build something to avoid the frustrating and painful hacky workarounds we had encountered with other commerce platforms. And now, thousands of companies are using Medusa, including fast-moving startups and some of the world’s largest companies. It’s hard to explain how happy and proud we are to share our work with you, and our top priority continues to be improving your experience.

## Taming complexity in your stack

Companies reach for Medusa to manage complex workflows that SaaS providers and other open-source tools can’t handle. Examples of complexity we have seen include gathering customer data across different channels to deliver personalized experiences. Or fulfilling thousands of daily orders from hundreds of distribution centers in the way that best aligns with business strategies. Or creating a seamless B2B purchasing experience for highly configurable products. The complexity companies experience is especially common when multiple systems have to work together to deliver a customer experience or automate a business flow.

Many companies try to tame their complexity by building applications from scratch that tie systems together and define customizations; however, building the foundation for such applications takes focus from serving customers best. Medusa has proven to be a much better starting point for businesses to accomplish their customizations than anywhere else. Medusa already has standards for defining data models, custom business logic, and much more, all while being flexible and easy to work with. Instead of reinventing these standards, Medusa users can focus on defining the logic that gives customers the best experience and optimizes operations.

## Build custom digital commerce applications faster

Medusa 2.0 doubles down on ensuring Medusa is the best foundation for building custom digital commerce applications. This is achieved through a focus on supporting custom workflows involving multiple systems directly in Medusa. Today's digital commerce happens with help from different systems, whether point solutions, marketing tools, ERP systems, or custom-built internal systems. With many tools in a stack, a key challenge becomes aligning them and making them work together. Most tools and services have APIs and say they are composable. But they can merely only participate in a composable stack. No tool, except Medusa, helps businesses easily build the foundation for such a stack. And with Medusa 2.0, we will continue to make this much easier.

Two key changes in Medusa’s architecture will address this:

1.  We will make core commerce concepts like Products, Discounts, etc., pluggable so you can use Medusa’s APIs without necessarily having to use Medusa’s full commerce module suite.

2.  We will launch a new, powerful Workflow primitive to orchestrate modules and services to complete tasks in your digital commerce stack.

The outcome is that Medusa becomes a hub where your company’s systems can interact. With Medusa’s customization tools, it will be straightforward to build integrations, customer experiences, or internal business workflows from that central hub.

## Making Medusa's modules pluggable

Medusa's architecture has, from the beginning, been modular. The main Medusa package ships with a service for handling products, another for handling carts, another for handling discounts, and so on. The services provide great separation of concerns and make it easy to use them in customizations. All services, however, must run within the same server and database. This is not bad in itself, but it requires that Medusa stores a copy of your data from across your tools internally to make its features work. We are eliminating this dependency and thereby making Medusa pluggable with existing tools.  For example, if you have product data in an existing PIM system, you can integrate it deeply with Medusa. When a customer adds a product to their cart, we will fetch product information directly from the PIM system, and you can set up tax and discount rules for the products despite them not being part of Medusa's database.

![](/images/old-new.jpg)

We are moving services into standalone packages like `@medusajs/product` and `@medusajs/pricing` to achieve this. These modules work independently of the rest of Medusa and can be used within any Node environment, including compatible serverless runtimes. Simultaneously, within the Medusa package, we are defining interfaces to the modules to make Medusa's default API work with the new standalone modules. This work happens behind the `medusa_v2` feature flag.

## New primitives for building digital commerce flows

Soon, we will introduce Workflows -  a new, powerful primitive for digital commerce applications with Workflows. A Workflow is a sequence of queries and actions across your system that achieve a task. Medusa will ship a wide range of Workflows to create products, add to a cart, and other operations available in Medusa’s API today.

Workflows are customizable, so you can inject custom logic into core workflows. For example, you can run custom validation when customers update their shipping addresses. Or add rules governing who can add given products to a cart. Or create a product entry in your CMS system whenever a new product is created.

Given that Medusa may be mutating data in external systems - like a PIM for your product data - we are building error handling into Workflows. Medusa will automatically retry failed attempts to update data, and if the issue is permanent, Medusa’s Workflows will compensate for any previous data changes that may have happened.

![](/images/add-to-cart.jpg)

Developers will also be able to create custom Workflows, which opens the door for a broad range of use cases and makes Medusa the best place to build integrations between your systems.

Consider integrating purchase orders from your ERP with your warehouse management system's inbounds. You can easily build custom services for your ERP and WMS and then construct a workflow that processes the purchase order and forwards it to the WMS. Doing this through Medusa creates opportunities for better customer experiences, like decorating products with an expected restock date for your customers to know when their favorite product will become available. This is easy because your product data is readily available through Medusa. Additionally, with the workflows, you won't have to worry about stale data between systems as retries and compensations are built-in. This is just one example of how custom Workflows can be used. As you add more connections between systems in your stack and Medusa, the opportunities for what is possible with Workflows expand exponentially.

![](/images/medusa-connecter-76bb3996.jpg)

## A great toolbox for digital commerce applications

The Workflow primitive joins Medusa’s existing tools like API Routes for custom API request handlers, Admin Extensions to build dashboard UI extensions, EventBus and Subscribers for Pub/Sub, Services for custom business logic and connections to external systems, and, of course, Medusa’s commerce logic for core commerce functionality.

Medusa comes packed with many great defaults that would take years for internal teams in digital commerce businesses to build and even more effort to continue to improve. With Workflows and Medusa 2.0, we will lower the bar for adopting Medusa into your stack. You can, for instance, start using Medusa’s Workflows to integrate your systems and, at your own pace, adopt the commerce modules that make sense for you.

It’s important to note that while the architectural changes we have planned will enable more complex use cases, Medusa will still be simple to set up. Our default API will have minimal breaking changes, and we are committed to making the upgrade path for existing Medusa projects smooth and painless.

## What’s next?

Over the next couple of months, we will ship many new standalone commerce modules. Each of them will be a key milestone toward shipping Medusa 2.0, and we are excited to hear your feedback and inputs as they are made available.

You can expect our Workflows to be released very soon. The Workflow tools can be used independently of Medusa 2.0, so you will not have to wait long before using this new, powerful primitive. The timeline for when Medusa 2.0 is still TBD - [sign up for our newsletter](https://medusajs.com/changelog/) and [follow Medusa on X](https://x.com/medusajs) to stay tuned.


Toward Medusa 2.0

Today, we are excited to announce API Routes – a massive improvement of the developer experience of a core concept in Medusa’s extensibility toolbox.

We are highly committed to delivering a world-class experience across all our products. With our commerce primitives and tooling, developers can effortlessly build unique digital commerce applications at record speed.

## **API Routes**

API Routes in Medusa is a place for developers to add custom logic that HTTP requests can trigger. The endpoints have direct access to Medusa’s core services like the Product and Cart services and custom services added to your project or in installed plugins.

To create a custom endpoint in Medusa, developers have had to familiarize themselves with application routing and Express more generally. This created friction unrelated to our product, leading to frustration from users, the community, and our support team.

Today, we are introducing API Routes - drastically simplifying creating custom endpoints in Medusa.

Developers can now create custom routes using simple JavaScript without worrying about the intricacies of the Express Router. Routes are registered using the file system, an approach familiar to many from frameworks like Next.js and Svelte.

```ts
// api/admin/products/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"

export async function GET(req: MedusaRequest, res: MedusaResponse) {
	const productService = req.scope.resolve("productService")

	const products = await productService.list()

	res.json({ products })
}
```

The example above illustrates a few key points of API Routes:

*   Endpoint paths are inferred from the file path

*   `route.{ts|js}` is a special file that contains the router handlers

*   HTTP methods are defined by the route handler name; here `GET`

In the example above, we register a `GET` route at path `/admin/products`.

### **Dynamic Segments**

API Routes support dynamic URL segments and are similarly registered through the file system.

```ts
// api/admin/products/[id]/route.ts

import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { id } = req.params
	const { payload } = req.body

	const productService = req.scope.resolve("productService")

	const product = await productService.update(id, payload)

	res.json({ product })
}
```

In the example above, we register a `POST` route at path `/admin/products/:id`. The brackets in the file path, `api/admin/products/[id]/route.ts`, specify a parameter that can be accessed within the handler.

You can add as many dynamic segments as you’d like. However, if the parameter names clash, an error will be thrown, and your application will terminate.

### **Middlewares**

Adding middleware to routes has also been simplified. With API Routes, we are centralizing all middlewares in a file at `api/middlewares.{ts|js}`. In this file, you can register middleware to all endpoints, a subset of endpoints, or one at a time.

```ts
// api/middlewares.ts

export const config: MiddlewaresConfig = {
  routes: [
    {
      method: ["GET", "POST"],
      matcher: "/store/*",
      middlewares: [someStoreMiddleware],
    },
  ],
}
```

Per default, middleware is registered globally. The `matcher` option is required to configure the paths the middlewares apply to. The `method` option is used to configure the specific methods the middlewares apply to.

In the example above, we register a middleware, `someStoreMiddleware`, to all paths starting with `/store` that use HTTP methods `GET` and `POST`.

## **What’s next?**

We are excited to hear your thoughts about our new API Routes. If you have any feedback or experience issues, don’t hesitate to post on our GitHub Issues board or GitHub Discussions.

In the future, we plan to extend the `MedusaRequest` and `MedusaResponse` to offer an even better experience with access to types specific to our Request and Response context, such as the Awilix dependency container living at `req.scope`.

Track our progress on [X](https://twitter.com/medusajs) and in our [changelog](https://medusajs.com/changelog/).


Announcing API Routes

[Visionary Technologies](https://www.visionarytechnologies.co.nz/) has become a market leader in New Zealand for LED lighting technology, which it sells to business customers such as architects, electric trades, and similar. Together with their implementation partner, [Typed Development](https://www.typed.co.nz/), they used Medusa to deliver a new digital commerce experience for their B2B customers, creating a frictionless buying journey without intermediaries while automating their backend operations.

<callout icon="lightBulbSolid" button-label="Get started" 
button-url="https\://docs.medusajs.com/recipes/b2b">
**B2B Recipe**
Set up your own B2B shop with Medusa.
</callout>

## Simplifying the customer journey

Visionary develops, manufactures, and markets all its LED products in-house from its production facilities in New Zealand. Since its inception in 2012, the company has been at the forefront of providing high-quality lightning products at a fair price. Their competitive pricing has been made possible by their decision to forego wholesalers, which is a conventional industry practice.

With Medusa, the company has been able to automate manual buying processes that were otherwise handled by their sales team and go directly to their B2B customers. The result has been a simplified customer journey with a shorter time-to-market while freeing up time for the sales team to acquire new customers instead of handling orders.![visionary-customer-journey](/images/Visionary-Customer-journey.jpg)

## Advanced commerce needs

As with many B2B-focused webshops, Visionary had additional requirements to their commerce backend aside from handling traditional commerce tasks such as [products](https://docs.medusajs.com/modules/products/overview), [carts and checkout](https://docs.medusajs.com/modules/carts-and-checkout/overview), [orders](https://docs.medusajs.com/modules/orders/overview) etc. Specifically, they required:

*   **Unlimited Product variants:** The store should be able to support products with up to 300 variants, all with different prices, product pictures, etc.

*   **Customer login and authentication:** The store should only be accessible for authenticated users of companies Visionary works with.

*   **Multiple employees per customer:** Each B2B customer has multiple employees associated with them who all need to be able to purchase on the platform on behalf of their company.

*   **Special pricing and discounts:** Visionary wanted a loyalty engine where customers earn discounts and special benefits based on their spending levels.

*   **ERP synchronization:** Upon order completion, Medusa needs to synchronize orders with Visionary’s ERP system for order production and fulfillment.

While exploring available options, Typed Development quickly realized that most SaaS ecommerce solutions did not offer the required flexibility for the job. Instead, they adopted Medusa’s commerce modules, giving them the right commerce logic to get started quickly and the flexibility to meet Visionary’s custom requirements.

<quote name="Jono Allen" title="Founder of Typed Development">
We spent 3 to 4 days tweaking Shopify to handle our product complexity with little luck. Afterwards, we went to Medusa and within 3 hours we had one of the most complex variants set up, and using the Next-starter we had a basic store going within half a day.
</quote>

## Linking customers and companies

Visionary wanted the employees of their B2B customers to be able to handle purchasing on their own in the online store. This would allow Visionary's sales representatives to devote less time to handle customers' manual orders and instead focus on acquiring new customers. Additionally, existing B2B customers would enjoy a more seamless purchasing experience, enabling their employees to complete orders online easily.

To allow employees of B2B customers to make direct purchases, Typed Development has added an employee layer to Medusa. This ensures employees are associated with their respective companies when logging into the store. Once logged in, they can browse products and make purchases on behalf of their company. After an order is placed, the order information is sent to a custom ERP system for production and fulfillment. In this setup:

*   **Employees** own carts, which allows them to create orders.

*   **Companies** own orders, which means they handle payments via invoices upon order completion.

Aside from the employee account, each company has admin accounts that, aside from creating orders, can add new employees and view all order and billing information.

![b2b-purchasing-flow](/images/Visionary-Technologies-b2b-purchasing-flow.png)

## Building a custom loyalty engine for Medusa

Visionary wanted to reward loyal customers based on their online spending. To support this, Typed Development built a loyalty engine using [Medusa’s Pricing Strategies](https://docs.medusajs.com/modules/price-lists/price-selection-strategy), which allows them to override and discount prices based on the customer group to which the customer belongs. This way, Typed Development could group customers into loyalty tiers based on spending, with each tier having certain product discounts associated with it.

The custom loyalty engine itself consists of two primary tiering mechanisms:

*   **Upgrade tier:** This tier is determined by accumulating all customer spending to determine their loyalty tier. When a certain spending level is reached, the customer is upgraded to a new tier with better discounts.

*   **Retainer tier:** This tier is determined by customer spending in the past 12 months. Customers must meet a minimum spending threshold during the period to stay in their current tier. This prevents customers with low or no spending from remaining in their tier. The spending for the retainer tier is reset when a customer reaches a new tier.

This loyalty engine has created a transparent discount system that is fully automated to control the different discount tiers of each customer.

![loyalty-engine](/images/Visionary-Technologies-loyalty-engine.jpg)

## Towards full automation

By the end of 2023, Visionary expects to handle over 1,000 monthly orders through Medusa. With its B2B ecommerce foundation already in place, the company is now focused on digitalizing and automating even more of its processes.

Order fulfillment using Visionary’s ERP is one process they look to optimize. Currently, it requires a lot of manual copy-pasting of order data from Medusa into the ERP. Instead, Typed Development hopes to use Medusa’s new [Admin Widgets](https://docs.medusajs.com/admin/widgets) to extend the current order overview in Medusa, allowing Visionary to control delivery services and fulfillment for post-order creation directly within Medusa and afterward move that information into the ERP.

Typed Development believes that the decision to go with an open and extendible solution like Medusa gives them the flexibility needed to easily build these custom automations that will benefit Visionary’s sales operations in the future.

<quote name="Jono Allen" title="Founder of Typed Development">
We feel that Medusa gives us a lot of capabilities to actually go in our own direction in terms of customizing and changing things, while allowing us to look through the code as well. It is easy to use and really gives us full control over the setup.
</quote>


Visionary: Frictionless B2B ecommerce with Medusa

We are excited to announce new and improved authentication methods in Medusa, built in collaboration with community contributor [David Preininger](https://www.linkedin.com/in/david-preininger-217956236/).

This update introduces a new authentication method and establishes a clear separation between the now three supported methods: Session, API Token, and Bearer Authentication. The separation will make it more obvious what to use for different cases. Whether your focus is server-side communication or SPAs, our authentication primitives will meet your needs.

## **Authentication methods**

Following this update, Medusa supports three authentication methods that each serve specific use cases better.

### **Sessions**

Our session authentication remains unchanged. This method is suitable for traditional server-side rendered web applications, such as webshops, because of its user-friendliness. Users sign in once, and the authenticated session is maintained throughout the rest of the user’s journey browsing the application.

### **API token**

Our API token authentication method has been slightly updated to follow best practices and comply with established conventions. More specifically, the header type has changed from Authorization with a `Bearer` prefix to a custom header tightly coupled with Medusa, `x-medusa-access-token`. The former is, not shockingly, reserved for bearer authentication. This method is suitable for server-to-server communication without direct user involvement.

Below is an example of using API key authentication:

![api-key-authentication](/images/Untitled-bd22de40.png)

This is the only breaking change in version 1.17.0.

### **Bearer token**

Bearer token authentication is a new method that utilizes JWT tokens, making it a suitable choice for Jamstack applications. Use this type of authentication when serving content from an API to different clients, such as SPAs or mobile applications. Additionally, this method will eliminate issues related to cookie constraints in browsers.

## **The power of building in public**

This is yet another demonstration of the power of building open-source software. Our new and improved authentication methods were completed by David Preininger, who specializes in building customizable ecommerce solutions.

Thanks to David for his contribution. If you wish to contribute or have feature requests for Medusa, you are always welcome to contact our [core maintainers](https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md).

## **What’s next**

There are several possible follow-up improvements to the authentication system or applications that use it. We will likely update Medusa Admin to use JWT Bearer authentication as this is more suitable for the aforementioned reasons.

Furthermore, David is working on incorporating these changes into the Medusa Authentication plugin built by core Medusa engineer Adrien. The plugin allows merchants to use additional authentication providers, including Google and Auth0.

Finally, we are considering implementing two additional features to enhance the system's flexibility and capabilities further.

Firstly, we aim to add native support for extending the authentication system with custom methods. This will allow for a more seamless integration of authentication methods specific to your business.

Secondly, we plan to introduce API token management in Medusa Admin, eliminating the need for users to jump through hoops when wanting to use the API token authentication method.


New and improved authentication methods

[Foraged](https://www.foraged.com/) is a two-sided marketplace for fresh wild and specialty foods like berries, mushrooms, truffles, and more. Foragers, farmers, and local stores list their products through the platform’s vendor portal, and everything from home cooks to Michelin-starred restaurants buy the products through the Foraged website or app. Using Medusa, the team has developed a custom experience where vendors can manage their entire shop from their dashboard, which is powered by Medusa. Meanwhile, customers can message, follow, and place special orders with their favorite sellers.

## **Maximum flexibility to build a custom marketplace**

As producers and users of wild and specialty foods, Foraged founders Jack and Andy noticed the difficulties in selling and procuring these foods, which mostly happened locally or via small online communities. Driven by their passion for the area, they wanted to solve this problem via an online marketplace that would make wild and specialty foods more accessible to both professional and amateur chefs while giving small local businesses a new place to find customers.

<quote name="Jack Hamrick" title="Co-founder and CEO at Foraged">
If you take this very fragmented market and combine it with an incredibly passionate community and put that together on a platform marketplace, that’s a huge unlock.
</quote>

To build a first-of-its-kind wild and specialty food marketplace, they brought together a diverse team, including experienced engineers and a chef from Michelin-starred Noma, and later brought along prominent investors, including the[ VC firm Bessemer](https://techcrunch.com/2023/07/12/foraged-mushroom-marketplace-seed/).

![foraged-marketplace](/images/image%20(25).png)

For the proof of concept, Foraged attempted two approaches: customizing a WooCommerce shop and building their own custom platform. However, both approaches had shortcomings.

With the WooCommerce shop, vendors had performance issues during traffic peaks as the application quickly got bloated from handling too many integrations. With the custom-built solution, the engineering team encountered bugs and instabilities in their ecommerce platform at every release. This was problematic since Foraged wanted to do several weekly releases as a fast-scaling company. Additionally, it was challenging to develop all commerce-related functionality from the ground up.

To solve the challenges, the team decided to look for alternative options. Specifically, the team was looking to:

*   **Support multiple vendors,** ensuring each vendor is able to handle products, shipping, orders, customers, and discount logic for their own store.

*   **Extend** **admin functionality** beyond regular commerce logic, ensuring vendors can chat with customers, track store followers, and similar.

*   **Integrate with multiple outside services** to add functionalities to the platform, like Shippo to handle vendor shipments, Auth0 for store access control, Contentful for product enrichment, etc.

The solution needed to be easily customizable and extensible to meet these requirements. Additionally, it had to provide a good developer experience when integrating with third-party solutions. The team found Medusa's modular architecture the perfect starting point for this.

<quote name="Andy Conner" title="Co-founder and Head of Product at Foraged">
Medusa was a saving grace really. There was no other alternative that would give us the control and customization options needed to build the unique customer and vendor experiences we wanted.
</quote>

## **Vendor dashboard to manage everything**

With many smaller shops and sellers on the platform, operating the store as frictionlessly as possible was a top priority for Foraged. Leveraging Medusa enabled them to focus on crafting a seamless vendor experience instead of building table-stakes commerce logic. Medusa’s modules would provide the necessary commerce features out-of-the-box while also offering the flexibility to add custom elements and integrate with 3rd party services.

![](/images/Group%2075%20(2\).jpg)

A key element in the seamless vendor experience was to ensure vendors could manage all store operations directly from their admin dashboard. To do this, Foraged enabled vendors to directly interact with 3rd party systems from the Medusa Admin, which is easily extensible through on-page [widgets](https://docs.medusajs.com/admin/widgets) or [UI routes](https://docs.medusajs.com/admin/routes) to create new pages. Some of their custom extensions include:

*   **User authentication** for store admins to sign in to their store via a Gmail account or equivalent SSO option via [Auth0](https://auth0.com/).

*   **Store dashboard** to view order notifications, find relevant articles, and access store data such as sales numbers, product views, and top-selling products.

*   **Fulfillment management** enables merchants to create shipments, print shipping labels, and track deliveries directly in their Admin. A custom [Shippo](https://medusajs.com/plugins/medusa-fulfillment-shippo/) integration powers all this.

*   **Extended product information** allows vendors to enrich product pages with additional data such as custom measurement specifications (Ozs., ltr., kg. etc.) and more product pictures using Medusa’s [Contentful integration](https://docs.medusajs.com/plugins/cms/contentful).

*   **Message app for** customers to directly message vendors with order inquiries, product questions, and more powered by [SendBird](https://sendbird.com/). Vendors can manage all chats directly from their admin dashboard.

*   **Waitlist feature** allows vendors to receive notifications when a customer signs up for a [product that is currently out of stock](https://medusajs.com/plugins/medusa-plugin-restock-notification/).

*   **Follower lists** enable customers to follow and get notifications about their favorite stores’ products. Vendors can view all followers within their Admin Dashboard.

Medusa’s out-of-the-box functionalities, such as [order overviews](https://docs.medusajs.com/modules/orders/overview), [product management](https://docs.medusajs.com/modules/products/overview), [discounts](https://docs.medusajs.com/modules/discounts/overview), [gift cards](https://docs.medusajs.com/modules/gift-cards/overview), etc., created an easy-to-manage dashboard for the Foraged vendors. Likewise, Medusa’s functionality was easily linked to the storefront, allowing the team to quickly and efficiently ship a great customer-facing webpage for the vendor's products.

<video controls preload="none" style="object-fit: cover; max-height: unset; max-width: 100%; margin-left: auto; margin-right: auto;" poster="/images/foraged-cover.png">
<source src="/videos/foraged.mp4" type="video/mp4" />
</video>

## **Improved development speed**

In addition to providing the team with the flexibility to build a customized vendor and customer experience, Medusa enabled the team to move much faster than anticipated. Previously, they had a troubled release process with several instabilities, but now they can ship multiple times per week without issues. Furthermore, pre-built Medusa integrations for solutions such as [Contentful](https://docs.medusajs.com/plugins/cms/contentful), [Stripe](https://docs.medusajs.com/plugins/payment/stripe), [Algolia](https://docs.medusajs.com/plugins/search/algolia), and others helped the team quickly get up and running.

<quote name="Andy Conner" title="Co-founder and Head of Product at Foraged">
We now release to production several times a week as Medusa is just easy to work with. Shifting to Medusa has felt a bit like going from building a car from scratch to getting our own custom one where we just had to hook up the wires and put them together.
</quote>

Next up, the team is looking to include subscription payments, allowing customers to subscribe to certain specialty foods for monthly deliveries. Aside from this, they are working on enabling vendors to create storefront customizations and utilizing Algolia to power dynamically populated shopping experiences that make it easier for customers to discover relevant products on the marketplace.


Foraged: Building a custom marketplace experience with Medusa

Developers

Solutions

Company

Main Menu

Learn More

This plugin does not have a README.

If you want to learn how to use this plugin, we recommend one of the following steps:

1. Join our [Discord community](https://discord.gg/medusajs) and ask for help on how to use this plugin.
2. Reach out to the plugin's author to learn how to use it.