docs: revise recipe examples
This commit is contained in:
Shahed Nasser
@@ -7,24 +7,24 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
This document provides an example of implementing the digital product recipe.
|
||||
In this guide, you'll learn how to support digital products in Medusa.
|
||||
|
||||
<Note>
|
||||
When you install a Medusa application, you get a fully-fledged commerce platform with support for customizations. Medusa provides all features related to products and managing them, and its framework allows you to extend those features and implement your custom use case.
|
||||
|
||||
You can implement digital products as you see fit for your use case. This is only an example of one way to implement it.
|
||||
You can extend Medusa's product features to support selling, storing, and fulfilling digital products. In this guide, you'll customize Medusa to add the following features:
|
||||
|
||||
</Note>
|
||||
|
||||
## Features
|
||||
|
||||
By following this example, you’ll have a commerce application with the following features:
|
||||
|
||||
1. Digital products with multiple media items.
|
||||
1. Support digital products with multiple media items.
|
||||
2. Manage digital products from the admin dashboard.
|
||||
3. Handle and fulfill digital product orders.
|
||||
4. Allow customers to download their digital product purchases from the storefront.
|
||||
5. All other commerce features that Medusa provides.
|
||||
|
||||
<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/digital-product",
|
||||
@@ -42,14 +42,50 @@ By following this example, you’ll have a commerce application with the followi
|
||||
|
||||
---
|
||||
|
||||
## 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 the Digital Product 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. You can also optionally choose to install the [Next.js starter storefront](../../../nextjs-starter/page.mdx).
|
||||
|
||||
Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed in a separate 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.
|
||||
|
||||
<Note title="Ran to Errors?">
|
||||
|
||||
Check out the [troubleshooting guides](../../../../troubleshooting/create-medusa-app-errors/page.mdx) for help.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create the Digital Product Module
|
||||
|
||||
Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
|
||||
|
||||
@@ -213,7 +249,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.
|
||||
|
||||
@@ -272,7 +308,7 @@ This defines a link between `DigitalProductOrder` and the Order Module’s `Orde
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Run Migrations and Sync Links
|
||||
## Step 4: Run Migrations and Sync Links
|
||||
|
||||
To create tables for the digital product data models in the database, start by generating the migrations for the Digital Product Module with the following command:
|
||||
|
||||
@@ -290,7 +326,7 @@ npx medusa db:migrate
|
||||
|
||||
---
|
||||
|
||||
## Step 4: List Digital Products Admin API Route
|
||||
## Step 5: List Digital Products Admin 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.
|
||||
|
||||
@@ -381,7 +417,7 @@ Make sure to replace `{token}` with the JWT token you retrieved.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create Digital Product Workflow
|
||||
## Step 6: Create Digital Product 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.
|
||||
|
||||
@@ -632,7 +668,7 @@ You’ll test out the workflow in the next section.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Create Digital Product API Route
|
||||
## Step 7: Create Digital Product API Route
|
||||
|
||||
In this step, you’ll add the API route to create a digital product using the `createDigitalProductWorkflow`.
|
||||
|
||||
@@ -731,7 +767,7 @@ This adds a validation middleware to ensure that the body of `POST` requests sen
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Upload Digital Product Media API Route
|
||||
## Step 8: Upload Digital Product Media API Route
|
||||
|
||||
To upload the digital product media files, use Medusa’s File Module.
|
||||
|
||||
@@ -824,7 +860,7 @@ You’ll test out this API route in the next step as you use these API routes in
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Add Digital Products UI Route in Admin
|
||||
## Step 9: Add Digital Products UI Route in Admin
|
||||
|
||||
The Medusa Admin is customizable, allowing you to inject widgets into existing pages or add UI routes to create new pages.
|
||||
|
||||
@@ -1067,7 +1103,7 @@ Once you log in, you’ll find a new sidebar item, “Digital Products.” If yo
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Add Create Digital Product Form in Admin
|
||||
## Step 10: Add Create Digital Product Form in Admin
|
||||
|
||||
In this step, you’ll add a form for admins to create digital products. The form opens in a drawer or side window from within the Digital Products UI route you created in the previous section.
|
||||
|
||||
@@ -1443,7 +1479,7 @@ To use this digital product in later steps (such as to create an order), you mus
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Create Digital Product Fulfillment Module Provider
|
||||
## Step 11: Create Digital Product Fulfillment Module Provider
|
||||
|
||||
In this step, you'll create a fulfillment module provider for digital products. It doesn't have any real fulfillment functionality as digital products aren't physically fulfilled.
|
||||
|
||||
@@ -1560,7 +1596,7 @@ This is necessary to use the fulfillment provider's shipping option during check
|
||||
|
||||
---
|
||||
|
||||
## Step 11: Customize Cart Completion
|
||||
## Step 12: Customize Cart Completion
|
||||
|
||||
In this step, you’ll customize the cart completion flow to not only create a Medusa order, but also create a digital product order.
|
||||
|
||||
@@ -1840,7 +1876,7 @@ In a later step, you’ll add an API route to allow customers to view and downlo
|
||||
|
||||
---
|
||||
|
||||
## Step 12: Fulfill Digital Order Workflow
|
||||
## Step 13: Fulfill Digital Order Workflow
|
||||
|
||||
In this step, you'll create a workflow that fulfills a digital order by sending a notification to the customer. Later, you'll execute this workflow in a subscriber that listens to the `digital_product_order.created` event.
|
||||
|
||||
@@ -2051,7 +2087,7 @@ module.exports = defineConfig({
|
||||
|
||||
---
|
||||
|
||||
## Step 13: Handle the Digital Product Order Event
|
||||
## Step 14: Handle the Digital Product Order Event
|
||||
|
||||
A subscriber is an asynchronous function that, when an event is emitted, is executed. You can implement in subscribers features that aren't essential to the original flow that emitted the event.
|
||||
|
||||
@@ -2094,7 +2130,7 @@ To test out the subscriber, place an order with digital products. This triggers
|
||||
|
||||
---
|
||||
|
||||
## Step 14: Create Store API Routes
|
||||
## Step 15: Create Store API Routes
|
||||
|
||||
In this step, you’ll create three store API routes:
|
||||
|
||||
@@ -2323,7 +2359,7 @@ You’ll test out these API routes in the next step.
|
||||
|
||||
---
|
||||
|
||||
## Step 15: Customize Next.js Starter
|
||||
## Step 16: Customize Next.js Starter
|
||||
|
||||
In this section, you’ll customize the [Next.js Starter storefront](../../../../nextjs-starter/page.mdx) to:
|
||||
|
||||
@@ -2331,6 +2367,8 @@ In this section, you’ll customize the [Next.js Starter storefront](../../../..
|
||||
2. Add a new tab in the customer’s dashboard to view their purchased digital products.
|
||||
3. Allow customers to download the digital products through the new page in the dashboard.
|
||||
|
||||
If you haven't installed the Next.js Starter storefront in the first step, refer to [this guide](../../../../nextjs-starter/page.mdx#approach-2-install-separately) to learn how to install it.
|
||||
|
||||
### Add Types
|
||||
|
||||
In `src/types/global.ts`, add the following types that you’ll use in your customizations:
|
||||
|
||||
@@ -7,22 +7,15 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
This document provides an example of implementing the marketplace recipe for a restaurant-delivery platform, similar to Uber Eats.
|
||||
In this guide, you'll learn how to build a restaurant-delivery marketplace platform, similar to Uber Eats, 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 marketeplace functionalities natively, it provides features that you can extend and a framework to support all your customization needs to build a marketplace.
|
||||
|
||||
You can implement the marketplace as you see fit for your use case. This is only an example of one way to implement it.
|
||||
In this guide, you'll customize Medusa to build a restaurant-delivery platform with the following features:
|
||||
|
||||
</Note>
|
||||
|
||||
## Features
|
||||
|
||||
By following this example, you’ll have a restaurant-delivery platform with the following features:
|
||||
|
||||
1. Multiple restaurants with their own admin users and products.
|
||||
2. Drivers that handle the delivery of orders from restaurants to customers.
|
||||
3. Delivery handling, from the restaurant accepting the order to the driver delivering the order to the customer.
|
||||
4. Real-time tracking of the order’s delivery status.
|
||||
1. Manage restaurants, each having admin users and products.
|
||||
2. Manage drivers and allow them to handle the delivery of orders from restaurants to customers.
|
||||
3. Real-time delivery handling and tracking, from the restaurant accepting the order to the driver delivering the order to the customer.
|
||||
|
||||
<CardList items={[
|
||||
{
|
||||
@@ -47,23 +40,50 @@ This recipe is adapted from [Medusa Eats](https://github.com/medusajs/medusa-eat
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
## 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: "Publishable API key to send store requests. You can create it in the Medusa Admin or using the Admin API routes",
|
||||
link: "/storefront-development/publishable-api-keys"
|
||||
text: "Git CLI tool",
|
||||
link: "https://git-scm.com/downloads"
|
||||
},
|
||||
{
|
||||
text: "Recommended: Use the Redis Workflow Engine Module for improved tracking and storage of workflow executions."
|
||||
text: "PostgreSQL",
|
||||
link: "https://www.postgresql.org/download/"
|
||||
}
|
||||
]} />
|
||||
|
||||
## Step 1: Create a Restaurant 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. You can also optionally choose to install the [Next.js starter storefront](../../../nextjs-starter/page.mdx).
|
||||
|
||||
Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed in a separate 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.
|
||||
|
||||
<Note title="Ran to Errors?">
|
||||
|
||||
Check out the [troubleshooting guides](../../../../troubleshooting/create-medusa-app-errors/page.mdx) for help.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create a Restaurant Module
|
||||
|
||||
Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
|
||||
|
||||
@@ -179,7 +199,7 @@ module.exports = defineConfig({
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create a Delivery Module
|
||||
## Step 3: Create a Delivery Module
|
||||
|
||||
In this step, you’ll create the Delivery Module that defines delivery-related data models.
|
||||
|
||||
@@ -319,7 +339,7 @@ module.exports = defineConfig({
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Define Links
|
||||
## Step 4: Define Links
|
||||
|
||||
Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
|
||||
|
||||
@@ -419,7 +439,7 @@ This defines a link between the Delivery Module’s `delivery` data model and th
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Run Migrations and Sync Links
|
||||
## Step 5: Run Migrations and Sync Links
|
||||
|
||||
To create tables for the above data models in the database, start by generating the migrations for the Restaurant and Delivery Modules with the following commands:
|
||||
|
||||
@@ -438,7 +458,7 @@ npx medusa db:migrate
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create Restaurant API Route
|
||||
## Step 6: Create Restaurant 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.
|
||||
|
||||
@@ -637,7 +657,7 @@ If you’re calling this API route from a frontend client, make sure to set the
|
||||
|
||||
---
|
||||
|
||||
## Step 6: List Restaurants API Route
|
||||
## Step 7: List Restaurants API Route
|
||||
|
||||
In this step, you’ll create the API routes that retrieves a list of restaurants.
|
||||
|
||||
@@ -709,7 +729,7 @@ This returns the list of restaurants in the response.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Create User API Route
|
||||
## Step 8: Create User API Route
|
||||
|
||||
In this step, you’ll create the API route that creates a driver or a restaurant admin user.
|
||||
|
||||
@@ -1058,7 +1078,7 @@ This returns the created driver user.
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Delete Restaurant Admin API Route
|
||||
## Step 9: Delete Restaurant Admin API Route
|
||||
|
||||
In this step, you'll create a workflow that deletes the restaurant admin and its association to its auth identity, then use it in an API route.
|
||||
|
||||
@@ -1250,7 +1270,7 @@ Make sure to replace the first ID with the restaurant's ID, and the second ID wi
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Create Restaurant Product API Route
|
||||
## Step 10: Create Restaurant Product API Route
|
||||
|
||||
In this step, you’ll create the API route that creates a product for a restaurant.
|
||||
|
||||
@@ -1402,7 +1422,7 @@ The request returns the created product in the response.
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Create Order Delivery Workflow
|
||||
## Step 11: Create Order Delivery Workflow
|
||||
|
||||
In this step, you’ll create the workflow that creates a delivery. You’ll use it at a later step once a customer places their order.
|
||||
|
||||
@@ -1555,7 +1575,7 @@ In the workflow, you:
|
||||
|
||||
---
|
||||
|
||||
## Step 11: Handle Delivery Workflow
|
||||
## Step 12: Handle Delivery Workflow
|
||||
|
||||
In this step, you’ll create the workflow that handles the different stages of the delivery. This workflow needs to run in the background to update the delivery when an action occurs.
|
||||
|
||||
@@ -2086,7 +2106,7 @@ In the next steps, you’ll execute the workflow and see it in action as you add
|
||||
|
||||
---
|
||||
|
||||
## Step 12: Create Order Delivery API Route
|
||||
## Step 13: Create Order Delivery API Route
|
||||
|
||||
In this step, you’ll create the API route that executes the workflows created by the previous two steps. This API route is used when a customer places their order.
|
||||
|
||||
@@ -2269,7 +2289,7 @@ In the upcoming steps, you’ll add functionalities to update the delivery’s s
|
||||
|
||||
---
|
||||
|
||||
## Step 13: Accept Delivery API Route
|
||||
## Step 14: Accept Delivery API Route
|
||||
|
||||
In this step, you’ll create an API route that a restaurant admin uses to accept a delivery. This moves the `handleDeliveryWorkflow` execution from `notifyRestaurantStep` to the next step.
|
||||
|
||||
@@ -2706,7 +2726,7 @@ Meaning that the `handleDeliveryWorkflow`'s execution has moved to the `awaitDri
|
||||
|
||||
---
|
||||
|
||||
## Step 14: Claim Delivery API Route
|
||||
## Step 15: Claim Delivery API Route
|
||||
|
||||
In this step, you’ll add the API route that allows a driver to claim a delivery.
|
||||
|
||||
@@ -2851,7 +2871,7 @@ This indicates that the `handleDeliveryWorkflow`'s execution continued past the
|
||||
|
||||
---
|
||||
|
||||
## Step 15: Prepare API Route
|
||||
## Step 16: Prepare API Route
|
||||
|
||||
In this step, you’ll add the API route that restaurants use to indicate they’re preparing the order.
|
||||
|
||||
@@ -2941,7 +2961,7 @@ This message indicates that the `handleDeliveryWorkflow`'s execution has moved t
|
||||
|
||||
---
|
||||
|
||||
## Step 16: Ready API Route
|
||||
## Step 17: Ready API Route
|
||||
|
||||
In this step, you’ll create the API route that restaurants use to indicate that a delivery is ready for pick up.
|
||||
|
||||
@@ -3033,7 +3053,7 @@ This message indicates that the `handleDeliveryWorkflow`'s execution has moved t
|
||||
|
||||
---
|
||||
|
||||
## Step 17: Pick Up Delivery API Route
|
||||
## Step 18: Pick Up Delivery API Route
|
||||
|
||||
In this step, you’ll add the API route that the driver uses to indicate they’ve picked up the delivery.
|
||||
|
||||
@@ -3173,7 +3193,7 @@ This message indicates that the `handleDeliveryWorkflow`'s execution has moved t
|
||||
|
||||
---
|
||||
|
||||
## Step 18: Complete Delivery API Route
|
||||
## Step 19: Complete Delivery API Route
|
||||
|
||||
In this step, you’ll create the API route that the driver uses to indicate that they completed the delivery.
|
||||
|
||||
@@ -3263,10 +3283,12 @@ As the route sets the status of the `awaitDeliveryStep` to successful in the `ha
|
||||
|
||||
---
|
||||
|
||||
## Step 19: Real-Time Tracking in the Storefront
|
||||
## Step 20: Real-Time Tracking in the Storefront
|
||||
|
||||
In this step, you’ll learn how to implement real-time tracking of a delivery in a Next.js-based storefront.
|
||||
|
||||
You can use a custom Next.js project, or use Medusa's Next.js Starter storefront. If you haven't installed the Next.js Starter storefront in the first step, refer to [this documentation](../../../../nextjs-starter/page.mdx#approach-2-install-separately) to learn how to install it.
|
||||
|
||||
### Subscribe Route
|
||||
|
||||
Before adding the storefront UI, you need an API route that allows a client to stream delivery changes.
|
||||
|
||||
@@ -7,23 +7,22 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
This document provides an example of implementing the marketplace recipe.
|
||||
In this guide, you'll learn how to build a marketplace with Medusa.
|
||||
|
||||
When you install a Medusa application, you get a fully-fledged commerce platform with support for customizations. While Medusa doesn't provide marketeplace functionalities natively, it provides features that you can extend and a framework to support all your customization needs to build a marketplace.
|
||||
|
||||
In this guide, you'll customize Medusa to build a marketplace with the following features:
|
||||
|
||||
1. Manage multiple vendors, each having vendor admins.
|
||||
2. Allow vendor admins to manage the vendor’s products and orders.
|
||||
3. Split orders placed by customers into multiple orders for each vendor.
|
||||
|
||||
<Note>
|
||||
|
||||
You can implement the marketplace as you see fit for your use case. This is only an example of one way to implement it.
|
||||
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>
|
||||
|
||||
## Features
|
||||
|
||||
By following this example, you’ll have a marketplace with the following features:
|
||||
|
||||
1. Multiple vendors, each having vendor admins.
|
||||
2. Vendor admins manage the vendor’s products and orders.
|
||||
3. On order creation, the order is split into multiple orders for each vendor.
|
||||
4. All other commerce features that Medusa provides.
|
||||
|
||||
<CardList items={[
|
||||
{
|
||||
href: "https://github.com/medusajs/examples/tree/main/marketplace",
|
||||
@@ -41,14 +40,50 @@ By following this example, you’ll have a marketplace with the following featur
|
||||
|
||||
---
|
||||
|
||||
## 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 Marketplace 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. You can also optionally choose to install the [Next.js starter storefront](../../../nextjs-starter/page.mdx).
|
||||
|
||||
Afterwards, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed in a separate 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.
|
||||
|
||||
<Note title="Ran to Errors?">
|
||||
|
||||
Check out the [troubleshooting guides](../../../../troubleshooting/create-medusa-app-errors/page.mdx) for help.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Marketplace Module
|
||||
|
||||
Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
|
||||
|
||||
@@ -159,7 +194,7 @@ module.exports = defineConfig({
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Define Links to Product and Order Data Models
|
||||
## Step 3: Define Links to Product and Order Data Models
|
||||
|
||||
Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
|
||||
|
||||
@@ -217,7 +252,7 @@ This adds a list link between the `Vendor` and `Order` data models, indicating t
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Run Migrations and Sync Links
|
||||
## Step 4: Run Migrations and Sync Links
|
||||
|
||||
To create tables for the marketplace data models in the database, start by generating the migrations for the Marketplace Module with the following command:
|
||||
|
||||
@@ -235,7 +270,7 @@ npx medusa db:migrate
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Create Vendor Admin Workflow
|
||||
## Step 5: Create Vendor Admin 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.
|
||||
|
||||
@@ -357,7 +392,7 @@ You return the created vendor admin.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create Vendor API Route
|
||||
## Step 6: Create Vendor 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.
|
||||
|
||||
@@ -569,7 +604,7 @@ Use this token in the header of later requests that require authentication.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Add Product API Routes
|
||||
## Step 7: Add Product API Routes
|
||||
|
||||
In this section, you’ll add two API routes: one to retrieve the vendor’s products and one to create a product.
|
||||
|
||||
@@ -795,7 +830,7 @@ curl 'http://localhost:9000/vendors/products' \
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Create Vendor Order Workflow
|
||||
## Step 8: Create Vendor Order Workflow
|
||||
|
||||
In this step, you’ll create a workflow that’s executed when the customer places an order. It has the following steps:
|
||||
|
||||
@@ -1265,7 +1300,7 @@ To test this out, it’s recommended to install the [Next.js Starter storefront]
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Retrieve Vendor Orders API Route
|
||||
## Step 9: Retrieve Vendor Orders API Route
|
||||
|
||||
In this step, you’ll create an API route that retrieves a vendor’s orders.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -126,18 +126,18 @@ export const generatedEditDates = {
|
||||
"app/nextjs-starter/page.mdx": "2024-12-10T08:44:33.783Z",
|
||||
"app/recipes/b2b/page.mdx": "2024-10-03T13:07:44.153Z",
|
||||
"app/recipes/commerce-automation/page.mdx": "2024-10-16T08:52:01.585Z",
|
||||
"app/recipes/digital-products/examples/standard/page.mdx": "2024-12-09T16:18:45.973Z",
|
||||
"app/recipes/digital-products/examples/standard/page.mdx": "2024-12-11T10:06:00.843Z",
|
||||
"app/recipes/digital-products/page.mdx": "2024-10-03T13:07:44.147Z",
|
||||
"app/recipes/ecommerce/page.mdx": "2024-10-22T11:01:01.218Z",
|
||||
"app/recipes/integrate-ecommerce-stack/page.mdx": "2024-12-09T13:03:35.846Z",
|
||||
"app/recipes/marketplace/examples/vendors/page.mdx": "2024-12-09T15:31:38.266Z",
|
||||
"app/recipes/marketplace/examples/vendors/page.mdx": "2024-12-11T10:06:16.586Z",
|
||||
"app/recipes/marketplace/page.mdx": "2024-10-03T13:07:44.153Z",
|
||||
"app/recipes/multi-region-store/page.mdx": "2024-10-03T13:07:13.813Z",
|
||||
"app/recipes/omnichannel/page.mdx": "2024-10-03T13:07:14.384Z",
|
||||
"app/recipes/oms/page.mdx": "2024-07-01T10:21:19+03:00",
|
||||
"app/recipes/personalized-products/page.mdx": "2024-10-03T13:07:44.153Z",
|
||||
"app/recipes/pos/page.mdx": "2024-10-03T13:07:13.964Z",
|
||||
"app/recipes/subscriptions/examples/standard/page.mdx": "2024-12-09T15:31:52.311Z",
|
||||
"app/recipes/subscriptions/examples/standard/page.mdx": "2024-12-11T10:05:39.227Z",
|
||||
"app/recipes/subscriptions/page.mdx": "2024-10-03T13:07:44.155Z",
|
||||
"app/recipes/page.mdx": "2024-07-11T15:56:41+00:00",
|
||||
"app/service-factory-reference/methods/create/page.mdx": "2024-07-31T17:01:33+03:00",
|
||||
@@ -624,7 +624,7 @@ export const generatedEditDates = {
|
||||
"app/medusa-cli/commands/start/page.mdx": "2024-08-28T10:44:19.952Z",
|
||||
"app/medusa-cli/commands/telemtry/page.mdx": "2024-08-28T11:25:08.553Z",
|
||||
"app/medusa-cli/commands/user/page.mdx": "2024-08-28T10:44:52.489Z",
|
||||
"app/recipes/marketplace/examples/restaurant-delivery/page.mdx": "2024-12-09T16:19:05.709Z",
|
||||
"app/recipes/marketplace/examples/restaurant-delivery/page.mdx": "2024-12-11T10:05:52.851Z",
|
||||
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminCreateCustomerGroup/page.mdx": "2024-12-09T13:21:33.569Z",
|
||||
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminCreateReservation/page.mdx": "2024-12-09T13:21:34.505Z",
|
||||
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminCustomerGroup/page.mdx": "2024-12-09T13:21:33.569Z",
|
||||
|
||||
+1912
-4856
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user