Skip to main content
Skip to main content

Build Subscription-based Purchases

This document guides you through the different documentation resources that will help you build subscription-based purchasing in Medusa.


Subscription-based purchase allows customers to purchase products for a specified period, and the payment and fulfillment is processed within a regular interval in that period.

For example, a customer can purchase a book subscription box for a period of three months. Each month, the payment will be captured for that order and, if the payment is successful, the fulfillment will be processed.

Build Subscription-based PurchasesCustomize the backend and handle events to implement subscriptions
Extend entities
Handle events
Create a Scheduled Job
Customize Admin
Create a storefront
Deploy the backend

Save Subscription Details in the Database

Subscriptions have details related to the subscription interval, subscription period, and more.

Based on the approach you choose to implement the subscription logic (which is discussed in the next section), you might need to store different data in your backend.

If you want to store the subscription details in a new table in the database, you can do that by creating an entity. If you want to extend an existing entity in Medusa's core, such as the Order entity, to add details related to the subscription, you can extend an entity.

Decide on Subscription Approach

There are different ways to implement subscriptions in your Medusa backend. This document discusses two options: using Stripe subscriptions, or implementing subscriptions logic within the backend, independent of a specific payment provider.

Option 1: Using Stripe Subscriptions

Stripe provides a subscription payments that allows you to authorize payment on a subscription basis within Stripe. Stripe then handles checking for recurring payments and capturing payment at the specified interval.

This approach allows you to delegate the complications of implementing the subscription logic to Stripe, but does not support using other payment providers.

Medusa provides a Stripe plugin, however, it doesn't handle subscriptions. You can either use that plugin to add the subscription feature on top of it, or create a custom Stripe Subscription payment provider.

Option 2: Implement Subscription Logic

By implementing the subscription logic within your backend, you can have full control over the subscription logic. You'll also be independent of payment providers, allowing you to provide customers with more than payment provider option.

Implementing the logic depends on your use case, but you'll mainly need to do two things:

  1. Perform an action when an order is placed, such as saving subscription details. This can be done using subscribers, which register handler functions to be triggered when an event is emitted. When an order is placed, the order.placed event is emitted.
  2. Check daily for subscriptions that need renewal. This can be done using a scheduled job, which is a cron job that can be executed on a defined interval. Within that job, you can define your renewal logic.

Customize Admin

As you add subscription features to your store, you'll most likely need to customize the admin to provide an interface to manage these features.

Medusa's admin plugin can be extended to add widgets or new blocks to existing pages, add UI routes to add new pages, or add setting pages.

Build a Storefront

Medusa provides a Next.js Starter Template that you can use with Medusa. Since you've customized your Medusa project, you'll need to either customize the existing Next.js Starter Template, or create a custom storefront.

Deploy Backend

Our documentation includes deployment guides for a basic Medusa backend. You should be able to follow it to deploy your customized backend, as well.

Additional Development

You can find other resources for your development in the Medusa Development section of this documentation.

Was this section helpful?