Subscriptions Recipe

This recipe provides the general steps to build subscription-based purchase with Medusa.

Overview#

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 is captured for that order and, if the payment is successful, the fulfillment is processed.

---

Save Subscription Details#

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

To store the subscription details, create a data model in a new subscription module. The module's main service provides data management feature of the data model.

You can link the subscription data model to models of other modules, such as the Order Module's Order data model.

Create a Module

Learn how to create a module.

Create a Data Model

Learn how to create a data model.

---

Define Module Links#

Define a module link that links a data model from your subscription module with a data model from another module.

For example, you can link the subscription data model to the Order Module's Order data model.

If you want to create subscriptions on the product level, you can link the subscription data model to the Product Module's Product data model.

---

Implement Subscription Approach#

There are different ways to implement subscriptions in your Medusa application. This recipe covers two options.

Option 1: Custom Subscription Logic#

By implementing the subscription logic within your application, you have full control over the subscription logic. You'll also be independent of payment providers, providing customers with more than one payment provider.

Implementing the logic depends on your use case, but you'll mainly implement the following:

1. Create an API route in place of the Complete Cart Store API Route that creates a subscription for the order.
2. Create a scheduled job that checks daily for subscriptions that need renewal.
3. Create a scheduled job that checks daily for subscriptions that are expired.

Create an API Route

Learn how to create an API route.

Create a Scheduled Job

Learn how to create a scheduled job.

Option 2: Using Stripe Subscriptions#

Stripe provides a subscription payments feature 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 doesn't support using other payment providers.

Although Medusa provides a Stripe module provider, it doesn't handle subscriptions. You can create a custom Stripe Subscription module provider.

---

Customize Admin#

You can extend the admin to provide an interface to manage your custom features, such as view the subscriptions.

Extend the Medusa Admin to add widgets to existing pages or add new pages.

Create Admin Widget

Learn how to add widgets into existing admin pages.

Create Admin UI Routes

Learn how to add new pages to your Medusa Admin.

---

Build a Storefront#

Medusa provides a Next.js Starter. Since you've customized your Medusa project, you must either customize the existing Next.js Starter, or create a custom storefront.

Option 1: Use Next.js Starter

Install the Next.js Starter to customize it.

Option 2: Build Custom Storefront

Find guides for your storefront development.

Edit this page