This tutorial assumes you have a basic understanding of Medusa.js and Stripe. If you're new to either of these technologies, I recommend checking out the official documentation for Medusa.js and Stripe.

Introduction

Medusa.js is a powerful e-commerce platform that allows you to build highly customisable online stores that can handle complex business logic and scale. One of the key features of any e-commerce platform is the ability to handle subscriptions, which can be a complex task to implement.

In this tutorial, I'll show you how to implement Stripe Subscriptions with Medusa.js in a simplified way. I'll focus on the key aspects of the integration and provide you with a clear roadmap to follow.

Approach

The approach we'll take is to let Stripe handle the subscription management and only use Medusa.js to handle the post-purchase product and order management. This means that we'll use Stripe to create and manage subscriptions, and Medusa.js to handle the product and order management after a successful subscription purchase. The flow will look like this:

1. 1. A customer selects a subscription product on the ecommerce store.
2. 2. The customer is redirected to the Stripe Checkout page to complete the subscription.
3. 3. After a successful subscription purchase, Stripe sends a webhook with the subscription details.
4. 4. We then create a draft order within Medusa.js with the subscription product and customer details.
5. 5. We then mark it as paid, which will complete the order and trigger the fulfilment process, such as sending a confirmation email or shipping the product.
6. 6. The customer can then manage their subscription through the Stripe dashboard.

Limitations

The simplified approach has a few intentional limitations that you should be aware of:

1. No Subscription Management in Medusa.js: We won't be managing subscriptions within Medusa.js. All subscription management will be done through the Stripe dashboard.
2. Separate Checkout Flow: The customer will be redirected to the Stripe Checkout page to complete the subscription purchase so it's not possible to have a unified checkout experience with this method.
3. Payment Providor Dependency: This approach relies on Stripe as the payment provider. If you want to switch to another payment provider, you'll need to update the implementation.

For the majority of use cases, these limitations should be acceptable. If you need more control over the subscription management, you should consider using the official Medusa.js Subscription Recipe. Note that this is a substantially more complex implementation.

Stripe Setup

Before we start implementing the integration, you need to set up a few things in Stripe:

1. 1. Create a Stripe account if you don't have one already.
2. 2. Set up your Stripe account with your business details and payment information.
3. 3. Create a new product in the Stripe dashboard for your subscription product.
4. 4. Create a new price for the product with the subscription details (e.g.weekly, monthly or yearly).
5. 5. Create payment links in the Stripe dashboard for the subscription product.
6. 6. Set up a webhook in the Stripe dashboard to listen for subscription events.
7. 7. Retrieve your Stripe API keys from the Stripe dashboard and add them to your environment variables.

Add Stripe Products to your frontend

To allow customers to purchase subscriptions, you need to add a checkout button to your frontend. The button will redirect the customer to the Stripe Checkout page to complete the subscription purchase using the payment link you created in the Stripe dashboard.

How you add the Stripe Checkout button to your frontend will depend on your frontend technology stack, the design of your ecommerce store and the complexity of your subscription products.

Here's a simple example of how you can get the payment link for a specific subscription product using the Stripe API.

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY)

const getPaymentLink = async (req, res) => {
  try {
    const { productId } = req.body;

    const price = await stripe.prices.search({
      query: `product:'${productId}'`,
    });

    if (!price.data.length) {
      return res.status(404).json({ error: 'Price not found' });
    }

    const paymentLink = await stripe.paymentLinks.create({
      line_items: [
        {
          price: price.data[0].id,
          quantity: 1,
        }
      ],
      allow_promotion_codes: true,
      after_completion: {
        type: 'redirect',
        redirect: {
          url: 'https://yourshop.com/success',
        }
      },
    });

    return res.json({ url: paymentLink.url });

  } catch (error) {
    console.error('Error creating payment link:', error);
    return res.status(500).json({ error: 'Internal Server Error' });
  }
}

You can then use the paymentLink.url to redirect the customer to the Stripe Checkout page to complete the subscription purchase.

Handling Stripe Webhooks

After a successful subscription purchase, Stripe will send a webhook to your server with the subscription details. We need to listen for this webhook and create a draft order in Medusa.js with the subscription product and customer details.

Here's an example of how you can handle the Stripe webhook in your server:

const handleWebhook = async (req, res) => {

  if (req.method === 'POST') {
    try {
      const sig = req.headers['stripe-signature'];
      const webhookSecret = process.env.NEXT_PUBLIC_STRIPE_WEBHOOK_KEY;
      // Read the raw body buffer
      const buf = await buffer(req);

      // Verify the event using Stripe's signature
      const event = stripe.webhooks.constructEvent(buf, sig, webhookSecret);

      // Handle the event
      switch (event.type) {
        case 'invoice.paid':
          console.log('Invoice paid event received');
          await createMedusaOrder(event); // Create a draft order in Medusa.js
          break;
        default:
          // Unexpected event type
          console.log(`Unhandled event type ${stripeEvent.type}`);
          break;
      }

      // just inform stripe that you received the event
      res.send({ status: 'success' });
      return;
    } catch (error) {
      // lets handle any errors coming from stripe
      console.error('Error handling webhook:', error.message);
      res.status(500).json({ error: error.message })

      return;
    }
  }

  // if the request is not a POST request, we return a 404
  res.status(404).json({
    error: {
      code: 'not_found',
      message:
        "The requested endpoint was not found",
    },
  });
}

In the createMedusaOrder function, you can create a draft order in Medusa.js with the subscription product and customer details. You can use the Medusa.js API to create the order and mark it as paid. Here is an example of how you can create a draft order in Medusa.js:

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const getProduct = async (stripeProducts) => {
  if (!Array.isArray(stripeProducts)) {
    throw new Error('Expected an array of stripe products');
  }

  // Ensure we get the correct product by filtering out the shipping rate
  const validProducts = stripeProducts.filter(product => product.plan?.product !== 'shipping-rate');

  if (validProducts.length === 0) {
    throw new Error('No valid subscription products found in the order');
  }

  if (validProducts.length > 1) {
    console.warn(`Found ${validProducts.length} valid products, using the first one`);
  }

  const stripeProduct = validProducts[0];

  const id = stripeProduct.plan.product;
  const price = stripeProduct.amount;
  const title = stripeProduct.description;

  return {
    title: title,
    unit_price: price,
    quantity: 1,
  }
}

// handle the invoice paid event
const createMedusaOrder = async (stripeEvent) => {
  // get the region id
  const region_id = process.env.MEDUSA_REGION_ID;
  // get the shipping option id
  const option_id = process.env.MEDUSA_SHIPPING_OPTION_ID;

  const invoicePaid = stripeEvent.data.object;
  // Validate invoice data
  if (!invoicePaid?.lines?.data) {
    throw new Error('Invalid invoice data structure');
  }

  // Get the product from the invoice
  const product = await getProduct(invoicePaid.lines.data);

  if (invoicePaid.subscription && invoicePaid.subscription.includes('sub')) {

  // medusa is your Medusa.js client instance, you need to create it first.
    await medusa.admin.draftOrders.create({
      email: invoicePaid.customer_email,
      region_id,
      items: [
        product
      ],
      shipping_methods: [
        {
          option_id
        }
      ],
      billing_address: {
        first_name: invoicePaid.customer_name ? invoicePaid.customer_name.split(' ')[0] : '',
        last_name: invoicePaid.customer_name ? invoicePaid.customer_name.split(' ')[1] : '',
        address_1: invoicePaid.customer_address?.line1 || '',
        address_2: invoicePaid.customer_address?.line2 || '',
        city: invoicePaid.customer_address?.city || '',
        country_code: invoicePaid.customer_address?.country.toLowerCase() || 'gb',
        province: invoicePaid.customer_address?.state || '',
        postal_code: invoicePaid.customer_address?.postal_code || '',
      },
      shipping_address: {
        first_name: invoicePaid.customer_name ? invoicePaid.customer_name.split(' ')[0] : '',
        last_name: invoicePaid.customer_name ? invoicePaid.customer_name.split(' ')[1] : '',
        address_1: invoicePaid.customer_shipping?.address?.line1 || '',
        address_2: invoicePaid.customer_shipping?.address?.line2 || '',
        city: invoicePaid.customer_shipping?.address?.city || '',
        country_code: invoicePaid.customer_shipping?.address.country.toLowerCase() || 'gb',
        province: invoicePaid.customer_shipping?.address?.state || '',
        postal_code: invoicePaid.customer_shipping?.address?.postal_code || '',
      },
    }).then(({ draft_order }) => {
      // Mark the draft order as paid
      medusa.admin.draftOrders.markPaid(draft_order.id)
        .catch((err) => {
          console.log('Error marking draft order as paid:', error);
          })
    })
      .catch((err) => {
        console.log('Error creating draft order:', error);
      })

  } else {
    return console.log('Invoice paid but not a subscription order');
  }
}

This code snippet shows how you can create a draft order in Medusa.js with the subscription product and customer details after a successful subscription purchase. The order will then be treated as a regular order in Medusa.js and the fulfilment process will be triggered along with any post-purchase actions you have set up like customer emails.

Subscription Management

After the customer has completed the subscription purchase, they can manage their subscription through the Stripe dashboard. This can be added as a link in the customer account section of your ecommerce store and will allow customers to update their payment details, cancel their subscription, or change their subscription plan directly with stripe.

<a href="https://billing.stripe.com/p/login/<YOUR_STRIPE_PORTAL_ID>">
  Manage Subscription
</a>

Conclusion

In this tutorial, I've shown you how to implement Stripe Subscriptions with Medusa.js in a simplified way that is easy to understand and can be modified to suit your specific requirements.

There are many ways to extend this, for example handling stripe checkout and subscription management directly in your store, or adding more complex subscription features like trial periods or multiple subscription plans.

I hope this tutorial has been helpful and that you now have a clear roadmap for implementing Stripe Subscriptions with Medusa.js. If you have any questions or need further assistance, feel free to reach out to me using the contact form. You can also subscribe to my newsletter to receive updates on new tutorials and articles very infrequently!