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.
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.
Learn how to create an entity in Medusa.
Learn how to extend an entity in Medusa.
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.
Check out Medusa's stripe plugin to build subscription on top of it.
Create a Stripe Subscription payment processor from scratch.
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:
- 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.placedevent is emitted.
- 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.
Learn how to create a subscriber in Medusa.
Learn how to create a scheduled job in Medusa.
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.
Learn how to add widgets into existing admin pages.
Learn how to add new pages to your Medusa admin.
Learn how to add new page to the Medusa admin settings.
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.
Install the Next.js Starter Template to customize it.
Find useful resources to build your own storefront.
Our documentation includes deployment guides for a basic Medusa backend. You should be able to follow it to deploy your customized backend, as well.
Learn how to deploy your subscription-based backend to different hosting providers.
You can find other resources for your development in the Medusa Development section of this documentation.