import { AcademicCapSolid, Github } from "@medusajs/icons"

export const metadata = {
  title: `Subscriptions Recipe`,
}

# {metadata.title}

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.

<Note title="Related use-case">

[How Goodchef built subscription-based purchases with Medusa](https://medusajs.com/blog/goodchef/).

</Note>

---

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

<CardList items={[
  {
    href: "!docs!/learn/fundamentals/modules",
    title: "Create a Module",
    text: "Learn how to create a module.",
    icon: AcademicCapSolid,
  },
  {
    href: "!docs!/learn/fundamentals/modules#1-create-data-model",
    title: "Create a Data Model",
    text: "Learn how to create a data model.",
    icon: AcademicCapSolid,
  },
]} />

---

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

<Card
  href="!docs!/learn/fundamentals/module-links"
  title="Define a Module Link"
  text="Learn how to define a module link."
  icon={AcademicCapSolid}
/>

---

## 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](!api!/store#carts_postcartsidcomplete) that creates a subscription for the order.
2. Create a scheduled job that checks daily for subscriptions that need renewal.
3. Create another scheduled job that checks daily for subscriptions that are expired.

<CardList itemsPerRow={2} items={[
  {
    href: "!docs!/learn/fundamentals/api-routes",
    title: "Create an API Route",
    text: "Learn how to create an API route.",
    icon: AcademicCapSolid,
  },
  {
    href: "!docs!/learn/fundamentals/scheduled-jobs",
    title: "Create a Scheduled Job",
    text: "Learn how to create a scheduled job.",
    icon: AcademicCapSolid,
  }
]} />

### Option 2: Using Stripe Subscriptions

Stripe provides a [subscription payments feature](https://stripe.com/docs/billing/subscriptions/overview) 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.

<Card
  href="/references/payment/provider"
  title="Create Payment Module Provider"
  text="Learn how to create a payment module provider."
  icon={AcademicCapSolid}
/>

---

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

<CardList items={[
  {
    href: "!docs!/learn/fundamentals/admin/widgets",
    title: "Create Admin Widget",
    text: "Learn how to add widgets into existing admin pages.",
    icon: AcademicCapSolid,
  },
  {
    href: "!docs!/learn/fundamentals/admin/ui-routes",
    title: "Create Admin UI Routes",
    text: "Learn how to add new pages to your Medusa Admin.",
    icon: AcademicCapSolid,
  }
]} />

---

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

<CardList items={[
  {
    href: "/nextjs-starter",
    title: "Option 1: Use Next.js Starter",
    text: "Install the Next.js Starter to customize it.",
    icon: AcademicCapSolid,
  },
  {
    href: "/storefront-development",
    title: "Option 2: Build Custom Storefront",
    text: "Find guides for your storefront development.",
    icon: AcademicCapSolid,
  }
]} />
