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.

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 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
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 methods 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.

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 page helpful?
© 2023 Medusa, Inc. All rights reserved.