docs: revise recipe examples
This commit is contained in:
Shahed Nasser
@@ -7,17 +7,11 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
This document provides an example of implementing the subscription recipe.
|
||||
In this guide, you'll learn how to support subscription purchases with Medusa.
|
||||
|
||||
<Note>
|
||||
When you install a Medusa application, you get a fully-fledged commerce platform with support for customizations. While Medusa doesn't provide subscription-based purchases natively, it provides the framework to support you in implementing this feature.
|
||||
|
||||
You can implement the subscription recipe as you see fit for your use case. This is only an example of one way to implement it.
|
||||
|
||||
</Note>
|
||||
|
||||
## Features
|
||||
|
||||
By following this example, you’ll have a subscription commerce store with the following features:
|
||||
In this guide, you'll customize Medusa to implement subscription-based purchases with the following features:
|
||||
|
||||
1. Subscription-based purchases for a specified interval (monthly or yearly) and period.
|
||||
2. Customize the admin dashboard to view subscriptions and associated orders.
|
||||
@@ -25,6 +19,12 @@ By following this example, you’ll have a subscription commerce store with the
|
||||
4. Automatic subscription expiration tracking.
|
||||
5. Allow customers to view and cancel their subscriptions.
|
||||
|
||||
<Note>
|
||||
|
||||
This guide provides an example of an approach to implement digital products. You're free to choose a different approach using Medusa's framework.
|
||||
|
||||
</Note>
|
||||
|
||||
<CardList items={[
|
||||
{
|
||||
href: "https://github.com/medusajs/examples/tree/main/subscription",
|
||||
@@ -42,14 +42,52 @@ By following this example, you’ll have a subscription commerce store with the
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Install a Medusa Application
|
||||
|
||||
<Prerequisites items={[
|
||||
{
|
||||
text: "A new Medusa application installed.",
|
||||
link: "!docs!#get-started"
|
||||
text: "Node.js v20+",
|
||||
link: "https://nodejs.org/en/download"
|
||||
},
|
||||
{
|
||||
text: "Git CLI tool",
|
||||
link: "https://git-scm.com/downloads"
|
||||
},
|
||||
{
|
||||
text: "PostgreSQL",
|
||||
link: "https://www.postgresql.org/download/"
|
||||
}
|
||||
]} />
|
||||
|
||||
## Step 1: Create Subscription Module
|
||||
Start by installing the Medusa application on your machine with the following command:
|
||||
|
||||
```bash
|
||||
npx create-medusa-app@latest
|
||||
```
|
||||
|
||||
You'll first be asked for the project's name. Then, when you're asked whether you want to install the Next.js storefront, choose `Y` for yes.
|
||||
|
||||
Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name, and the Next.js storefront in a directory with the `{project-name}-storefront` name.
|
||||
|
||||
<Note title="Why is the storefront installed separately?">
|
||||
|
||||
The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](!docs!/learn/fundamentals/api-routes). Learn more about Medusa's architecture in [this documentation](!docs!/learn/introduction/architecture).
|
||||
|
||||
</Note>
|
||||
|
||||
Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credential and submit the form.
|
||||
|
||||
Afterwards, you can login with the new user and explore the dashboard. The Next.js storefront is also running at `http://localhost:8000`.
|
||||
|
||||
<Note title="Ran to Errors?">
|
||||
|
||||
Check out the [troubleshooting guides](../../../../troubleshooting/create-medusa-app-errors/page.mdx) for help.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Subscription Module
|
||||
|
||||
Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
|
||||
|
||||
@@ -178,7 +216,7 @@ module.exports = defineConfig({
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Define Links
|
||||
## Step 3: Define Links
|
||||
|
||||
Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
|
||||
|
||||
@@ -261,7 +299,7 @@ This defines a list link to the `Order` data model since a subscription has mult
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Run Migrations
|
||||
## Step 4: Run Migrations
|
||||
|
||||
To create a table for the `Subscription` data model in the database, start by generating the migrations for the Subscription Module with the following command:
|
||||
|
||||
@@ -279,7 +317,7 @@ npx medusa db:migrate
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Override createSubscriptions Method in Service
|
||||
## Step 5: Override createSubscriptions Method in Service
|
||||
|
||||
Since the Subscription Module’s main service extends the service factory, it has a generic `createSubscriptions` method that creates one or more subscriptions.
|
||||
|
||||
@@ -448,7 +486,7 @@ This method is used in the next step.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create Subscription Workflow
|
||||
## Step 6: Create Subscription Workflow
|
||||
|
||||
To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow.
|
||||
|
||||
@@ -676,7 +714,7 @@ The workflow returns the created subscription and order.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Override Complete Cart API Route
|
||||
## Step 7: Override Complete Cart API Route
|
||||
|
||||
To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route.
|
||||
|
||||
@@ -753,7 +791,7 @@ Then, you use the `createSubscriptionWorkflow` you created to create the order,
|
||||
|
||||
### Storefront Customization
|
||||
|
||||
In this section, you'll customize the checkout flow in the [Next.js Starter storefront](../../../../nextjs-starter/page.mdx) to include a subscription form.
|
||||
In this section, you'll customize the checkout flow in the [Next.js Starter storefront](../../../../nextjs-starter/page.mdx), which you installed in the first step, to include a subscription form.
|
||||
|
||||
After installation, create the file `src/modules/checkout/components/subscriptions/index.tsx` with the following content:
|
||||
|
||||
@@ -990,7 +1028,7 @@ npm run dev
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Add Admin API Routes for Subscription
|
||||
## Step 8: Add Admin API Routes for Subscription
|
||||
|
||||
In this step, you’ll add two API routes for admin users:
|
||||
|
||||
@@ -1106,7 +1144,7 @@ In the next section, you’ll extend the Medusa admin and use these API routes t
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Extend Admin
|
||||
## Step 9: Extend Admin
|
||||
|
||||
The Medusa Admin is customizable, allowing you to inject widgets into existing pages or add UI routes to create new pages.
|
||||
|
||||
@@ -1469,7 +1507,7 @@ To view a subscription’s details, click on its ID, which opens the subscriptio
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Create New Subscription Orders Workflow
|
||||
## Step 10: Create New Subscription Orders Workflow
|
||||
|
||||
In this step, you’ll create a workflow to create a new subscription order. Later, you’ll execute this workflow in a scheduled job.
|
||||
|
||||
@@ -1895,7 +1933,7 @@ In the next step, you’ll execute the workflow in a scheduled job.
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Create New Subscription Orders Scheduled Job
|
||||
## Step 11: Create New Subscription Orders Scheduled Job
|
||||
|
||||
A scheduled job is an asynchronous function executed at a specified interval pattern. Use scheduled jobs to execute a task at a regular interval.
|
||||
|
||||
@@ -2012,7 +2050,7 @@ This loops over the returned subscriptions and executes the `createSubscriptionO
|
||||
|
||||
---
|
||||
|
||||
## Step 11: Expire Subscriptions Scheduled Job
|
||||
## Step 12: Expire Subscriptions Scheduled Job
|
||||
|
||||
In this step, you’ll create a scheduled job that finds subscriptions whose `expiration_date` is the current date and marks them as expired.
|
||||
|
||||
@@ -2129,7 +2167,7 @@ You also implement pagination in case there are more than `20` expired subscript
|
||||
|
||||
---
|
||||
|
||||
## Step 12: Add Customer API Routes
|
||||
## Step 13: Add Customer API Routes
|
||||
|
||||
In this step, you’ll add two API routes for authenticated customers:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user