asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: update recipe contents (#12515)

Browse Source
This commit is contained in:
Shahed Nasser
2025-05-16 16:37:52 +03:00
committed by GitHub
parent 399dddc0c7
commit d73cf66196
15 changed files with 16168 additions and 15896 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31180
www/apps/book/public/llms-full.txt
View File

File diff suppressed because it is too large Load Diff

136
www/apps/resources/app/recipes/b2b/page.mdx
View File

@@ -18,7 +18,13 @@ Medusa has a ready-to-use B2B starter that you install and use in [this GitHub r
In a B2B store, you provide different types of customers with relevant pricing, products, shopping experience, and more.
Medusa’s Commerce Modules, including Sales Channel, Customer, and Pricing modules facilitate implementing this setup. Medusa’s architecture and extendible nature allow you to customize your store based on your use case.
Medusa’s Commerce Modules, including [Sales Channel](../../commerce-modules/sales-channel/page.mdx), [Customer](../../commerce-modules/), and [Pricing](../../commerce-modules/pricing/page.mdx) modules enable this setup out-of-the-box:
- **Sales Channel**: Use sales channels to set product availability per channel. In this case, create a B2B sales channel that includes only B2B products.
- **Customer**: Use customer groups to organize your customers into different groups. Then, you can apply different prices for each group.
- **Pricing**: Use price lists to set different prices for each B2B customer group, among other conditions.
In addition, Medusa’s extensible architecture and Framework for customization allow you to scope existing and custom featuers to specific customer groups or sales channels.
<Note title="Related use-case">
@@ -30,7 +36,9 @@ Medusa’s Commerce Modules, including Sales Channel, Customer, and Pricing modu
## Create B2B Sales Channel
Use sales channels to set product availability per channel. In this case, create a B2B sales channel that includes only B2B products.
Sales channls allow you to set product availability per channel. For B2B use cases, you can create a B2B sales channel that includes only B2B products.
Then, on the storefront, your retrieve only the B2B products for B2B customers, which is explained more in the next section.
You can create a sales channel through the Medusa Admin or Admin REST APIs.
@@ -53,16 +61,16 @@ You can create a sales channel through the Medusa Admin or Admin REST APIs.
## Create a Publishable API Key
Use publishable API keys to specify the context of client requests:
A publishable API key allows you to specify the context of client requests:
- You associate the publishable API key with one or more sales channels.
- You associate the publishable API key with one or more sales channels, such as the B2B sales channel.
- In a client such as a storefront, you pass the publishable API key in the header of your requests.
Then, all products retrieved belong to the associated sales channel(s).
So, if you use the publishable API key associated with the B2B sales channel in your storefront, the Medusa server will only return products that are available in the B2B sales channel.
You can create a publishable API key through the Medusa Admin or the Admin REST APIs, then associate it with the B2B sales channel. Later, you'll use this key when developing your B2B storefront.
You can create a publishable API key through the Medusa Admin or the Admin REST APIs, then associate it with the B2B sales channel. Then, you can use this key when developing your B2B storefront.
### Create Key
### Create Publishable API Key
<CardList items={[
{
@@ -100,6 +108,8 @@ You can create a publishable API key through the Medusa Admin or the Admin REST
## Add Products to B2B Sales Channel
You can manage products to be available in specific sales channels. For B2B, this allows you to add products that are only available to B2B customers.
You can create new products or add existing ones to the B2B sales channel using the Medusa Admin or Admin REST APIs.
### Create Products
@@ -138,34 +148,13 @@ You can create new products or add existing ones to the B2B sales channel using
---
## Create B2B Module with Relationship to Customer Groups
## Add B2B Customers and Groups
Use customer groups to organize your customers into different groups. Then, you can apply different prices for each group.
Customer groups allow you to organize your customers into different groups. Then, you can apply different prices for each group.
This is useful in B2B sales, as you often negotiate special prices with each customer or company.
This is useful for B2B sales, as you often negotiate special prices with each customer or company.
You can create a B2B module that adds necessary data models to represent a B2B company. Then, you link that company to a customer group, which is defined in the Customer Module. Any customer belonging to that group also belongs to the company, meaning they're a B2B customer.
<CardList items={[
{
href: "!docs!/learn/fundamentals/modules",
title: "Create Module",
text: "Learn how to create a module.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/module-links",
title: "Define Module Links",
text: "Define links between data models.",
icon: AcademicCapSolid,
},
]} />
## Add B2B Customers
After adding your B2B customer group, add B2B customers and assign them to the B2B customer group.
You can do that through the Medusa Admin or Admin REST APIs.
You can create a customer group for each B2B company, then add customers of that company to the group.
### Create Customers
@@ -201,13 +190,38 @@ You can do that through the Medusa Admin or Admin REST APIs.
},
]} />
### Flexible Customizations: Create Custom Module
B2B use cases often require more complex customer management, such as managing roles in a company with employees having different privileges.
For more complex use cases, you can create a custom module that introduces data models like `Company`, `Employee`, and other relevant models.
Then, you can link those companies to existing customers and groups, allowing you to benefit from existing features like price lists for specific customer groups.
<CardList items={[
{
href: "!docs!/learn/fundamentals/modules",
title: "Create Module",
text: "Learn how to create a module.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/module-links",
title: "Define Module Links",
text: "Define links between data models.",
icon: AcademicCapSolid,
},
]} />
---
## Create B2B Price List
Use price lists to set different prices for each B2B customer group, among other conditions.
Price lists allow you to set different prices for each customer group, among other conditions. They're useful to override prices for custom use cases.
You can create a price list using the Medusa Admin or the Admin REST APIs. Make sure to set the B2B customer group as a condition.
For B2B use cases, you can use price lists to set different prices for each B2B customer group. Then, B2B customers can see different prices on the storefront based on their group.
You can create a price list using the Medusa Admin or the Admin REST APIs. Make sure to set the B2B customer group(s) as a condition.
<CardList items={[
{
@@ -226,41 +240,17 @@ You can create a price list using the Medusa Admin or the Admin REST APIs. Make
---
## Create Custom Data Model
To implement a more advanced B2B sales flow, add custom data models such as `Company`, `Employee`, `Admin`, and `Buyer` to your B2B module.
This provides more granular control of your B2B sales and allows you to build features like privileges, limits, and more.
<Card
href="!docs!/learn/fundamentals/modules#1-create-data-model"
title="Create a Data Model"
text="Learn how to create a custom data model in a module."
icon={AcademicCapSolid}
/>
---
## Create an API Route to Check Customers
On the frontend clients communicating with your store, such as the storefront, you need to check whether the currently logged-in customer is a B2B customer.
The API route can check if the customer has any group with an associated company.
<Card
href="!docs!/learn/fundamentals/api-routes"
title="Create an API Route"
text="Learn how to create an API Route in Medusa."
icon={AcademicCapSolid}
/>
---
## Customize Admin
## Customize Medusa Admin
Based on your use case, you may need to customize the Medusa Admin to add new widgets or pages.
The Medusa Admin plugin can be extended to add widgets, new pages, and setting pages.
For example, you may want to add a page to manage companies and their employees, or you may want to add a widget to show the company associated with a customer group.
The Medusa Admin is an extensible application within your Medusa application. You can customize it by:
- **Widgets**: Adding widgets to existing pages, such as the customer group page.
- **UI Routes**: Adding new pages to the Medusa Admin, such as a page to manage companies and employees.
- **Settings Pages**: Adding new pages to the Medusa Admin settings, such as a page to manage company settings.
<CardList items={[
{
@@ -287,23 +277,25 @@ The Medusa Admin plugin can be extended to add widgets, new pages, and setting p
---
## Customize Storefront
## Customize or Build Storefront
Medusa provides a Next.js storefront to use with your application. You can either customize it or build your own to represent your B2B features.
Medusa provides a Next.js Starter Storefront to use with your application. You can customize it to for your B2B use case, such as adding a login page for B2B customers or expanding the profile page to show the company associated with the customer.
Use the publishable API key you associated with your B2B sales channel in the storefront to ensure only B2B products are retrieved.
Alternatively, you can build your own storefront using the Medusa APIs. This headless approach gives you the flexibility to build a custom storefront without limitations on which tech stack you use, or the design of the storefront.
In your storefront, you can use the publishable API key you associated with your B2B sales channel to ensure only B2B products are retrieved.
<CardList items={[
{
href: "/nextjs-starter",
title: "Next.js Storefront",
text: "Learn how to install and customize the Next.js storefront.",
title: "Next.js Starter Storefront",
text: "Learn how to install and customize the Next.js Starter Storefront.",
icon: AcademicCapSolid,
},
{
href: "/storefront-development",
title: "Storefront Development",
text: "Find guides for your storefront development.",
text: "Find guides to build your own storefront.",
icon: AcademicCapSolid,
},
]} />

10
www/apps/resources/app/recipes/bundled-products/page.mdx
View File

@@ -9,9 +9,11 @@ export const metadata = {
This recipe provides the general steps to implement bundled products in your Medusa application.
## Example Guide
<Note>
<ChildDocs type="item" onlyTopLevel={true} />
Follow the step-by-step [Bundled Products Example](./examples/standard/page.mdx) to learn how to implement bundled products in your Medusa application.
</Note>
## Overview
@@ -170,8 +172,8 @@ Alternatively, you can build the storefront with your preferred tech stack.
<CardList items={[
{
href: "/nextjs-starter",
title: "Next.js Starter",
text: "Learn how to install and use the Next.js Starter storefront.",
title: "Next.js Starter Storefront",
text: "Learn how to install and use the Next.js Starter Storefront.",
icon: AcademicCapSolid,
},
{

83
www/apps/resources/app/recipes/commerce-automation/page.mdx
View File

@@ -18,7 +18,11 @@ Medusa provides the necessary architecture and tools to implement commerce autom
## Re-Stock Notifications
Customers may be interested in a product that is currently out of stock. The following guide explains how to add restock notifications in your Medusa application:
Customers may be interested in a product that is currently out of stock. Instead of losing their interest, you can allow them to subscribe to receive a notification when the product is back in stock.
Then, you can listen to product-related events and notify subscribed customers when a product variant is back in stock.
The following guide explains how to add restock notifications in your Medusa application:
<Card
href="/recipes/commerce-automation/restock-notification"
@@ -31,17 +35,36 @@ Customers may be interested in a product that is currently out of stock. The fol
## Automated Customer Support
Customer support is essential to build a store's brand and customer loyalty. This can include integrating with third-party services or automating notifications sent to customers when changes happen related to their orders, returns, exchanges, and more.
Customer support is essential to build a store's brand and customer loyalty. However, to provide an efficient customer support, you often need to integrate with third-party services, like Zendesk, and automate customer notifications.
You can use the Notification Module to send notifications when an action is triggered, such as when a customer or their order is updated.
### Integrate with Third-Party Services
<Note title="Tip">
To provide customer support, you can Integrate with third-party services, such as ticket systems or chat bots in the storefront.
The [Events reference](/references/events) shows an extensive list of events triggered for each Commerce Module.
Medusa allows you to easily integrate with third-party services by creating a custom module, then build workflows for your business logic that perform actions with the third-party service.
</Note>
This approach allows you to interact with the third-party service within custom and existing flows, while maintaining data consistency across systems. You can then execute the wokflow when an event is triggered, such as when a customer places an order or requests a return.
Medusa also provides Notification Module Providers that integrate with third-party services, such as SendGrid.
<CardList items={[
{
href: "!docs!/learn/fundamentals/modules",
title: "Create Module",
text: "Learn about how to create a custom module.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/workflows",
title: "Create Workflow",
text: "Learn how to create a workflow.",
icon: AcademicCapSolid,
},
]} />
### Automate Customer Notifications
You can also automate sending notifications to customers when changes happen related to their orders, returns, exchanges, and more.
Medusa's Notification Module allows you to send notifications when an event is triggered, such as when a customer's order is updated. You can use third-party services, like [SendGrid](../../infrastructure-modules/notification/sendgrid), to send emails to customers.
<CardList items={[
{
@@ -64,25 +87,45 @@ Medusa also provides Notification Module Providers that integrate with third-par
As your commerce store grows, you'll likely need to synchronize data across different systems. For example, you need to synchronize data with an ERP system or a data warehouse.
To implement that:
<Note title="Integrating an ERP?">
- Create a workflow that implements the synchronization steps, along with retry and rollback logic.
Refer to the [ERP](../erp/page.mdx) recipe for a focused guide on how to integrate with an ERP system.
</Note>
To implement that, you can:
- Create a workflow that implements the synchronization steps, along with retry and rollback logic. By using a workflow, you ensure data consistency across systems.
- Create a scheduled job that executes the workflow automatically at the specified time pattern.
<Card
href="!docs!/learn/fundamentals/scheduled-jobs"
title="Create a Scheduled Job"
text="Learn how to create a scheduled job in Medusa."
icon={AcademicCapSolid}
/>
<CardList items={[
{
href: "!docs!/learn/fundamentals/workflows",
title: "Create Workflow",
text: "Learn how to create a workflow.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/scheduled-jobs",
title: "Create a Scheduled Job",
text: "Learn how to create a scheduled job.",
icon: AcademicCapSolid,
},
]} />
---
## Order Management Automation
Using Medusa's architecture and commerce features, you can automate a large amount of order management functionalities.
Medusa's architecture, Commerce Modules, and Framework for customizations facilitate automating a large amount of order management functionalities.
To handle events within an order flow and automate actions, create a subscriber. For example, create a subscriber that listens to the `order.placed` event and automatically creates a fulfillment if predefined conditions are met.
For example, you can automatically:
- Create a fulfillment when an order is placed.
- Create a refund when an item is returned.
- Send a notification when an order is shipped.
To handle events within an order flow and automate actions, you can create a subscriber that listens to the relevant event. For example, you can create a subscriber that listens to the `order.placed` event and automatically creates a fulfillment if predefined conditions are met.
<CardList items={[
{
@@ -134,8 +177,8 @@ Businesses use customer segmentation to organize customers into different groups
Medusa's Commerce Modules provide the necessary features to implement this use case:
- The Customer Module provides a customer groups feature to organize customers into customer groups.
- The Pricing Module provides the features to specify prices based on a condition, such as the group of the customer.
- The Customer Module allows you to organize customers into customer groups.
- The Pricing Module allows you to specify prices based on a condition, such as the group of the customer.
For example, to group customers with over twenty orders:
@@ -175,7 +218,7 @@ For example, to group customers with over twenty orders:
In your commerce store, you may utilize marketing strategies that encourage customers to make purchases. For example, you send a newsletter when new products are added to your store.
To do that, create a subscriber that listens to the `product.created`, and send an email to subscribed customers with tools like SendGrid or Mailchimp.
To do that, create a subscriber that listens to the `product.created`, and send an email to subscribed customers with tools like [SendGrid](../../infrastructure-modules/notification/sendgrid/page.mdx).
You can also create a scheduled job that checks whether the number of new products has exceeded a set threshold, then sends out the newsletter.

101
www/apps/resources/app/recipes/digital-products/page.mdx
View File

@@ -9,13 +9,17 @@ export const metadata = {
This recipe provides the general steps to implement digital products in your Medusa application.
## Example Guides
<Note>
<ChildDocs type="item" onlyTopLevel={true} />
Follow the step-by-step [Digital Products Example](./examples/standard/page.mdx) to learn how to implement digital products in your Medusa application.
</Note>
## Overview
Digital products are stored privately using a storage service like S3. When the customer buys this type of product, an email is sent to them where they can download the product.
Digial products are products that are stored and deliveerd electronically. Examples include e-books, software, and digital art.
When the customer buys a digital product, an email is sent to them where they can download the product.
To implement digital products in Medusa, you create a Digital Product Module that introduces the concept of a digital product and link it to existing product concepts in the Product Module.
@@ -25,9 +29,9 @@ To implement digital products in Medusa, you create a Digital Product Module tha
A file module provider handles storage functionalities in Medusa. This includes uploading, retrieving, and downloading files, among other features.
Use a file module provider to manage your stored digital products.
You can use a file module provider to store and manage your digital products.
During development, you can use the Local File Module Provider, which is installed by default in your store. For production, check out available file module providers or create your own.
During development, you can use the Local File Module Provider, which is installed by default in your store. For production, you can use module providers like [S3](../../infrastructure-modules/file/s3/page.mdx) or create your own.
<CardList items={[
{
@@ -50,7 +54,7 @@ During development, you can use the Local File Module Provider, which is install
Your custom features and functionalities are implemented inside modules. The module is integrated into the Medusa application without any implications on existing functionalities.
The module will hold your custom data models and the service implementing digital-product-related features.
You can create a custom module for digital products that holds your custom data models and the service implementing digital-product-related features.
<Card
href="!docs!/learn/fundamentals/modules"
@@ -95,7 +99,7 @@ Medusa facilitates implementing data-management features using the service facto
---
## Implement Workflows
## Build Flows for Digital Products
Your use case most likely has flows, such as creating digital products, that require multiple steps.
@@ -116,7 +120,7 @@ In the workflow's steps, you can resolve the Digital Product Module's service an
API routes expose your features to external applications, such as the admin dashboard or the storefront.
You can create custom API routes that allow merchants to list and create digital products.
You can create custom admin API routes that allow merchants to list and create digital products, and store API routes that allow customers to purchase and download digital products.
<Card
href="!docs!/learn/fundamentals/api-routes"
@@ -127,64 +131,65 @@ You can create custom API routes that allow merchants to list and create digital
---
## Manage Linked Records
If you've defined links between data models of two modules, you can manage them through two tools: Link and Query.
Use Link to create a link between two records, and use Query to fetch data across linked data models.
<CardList itemsPerRow={2} items={[
{
href: "!docs!/learn/fundamentals/module-links/link",
title: "How to Use Link",
text: "Learn how to link data models of different modules.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/module-links/query",
title: "How to Use Query",
text: "Learn how to fetch data across modules with Medusa's Query.",
icon: AcademicCapSolid,
},
]} />
---
## Customize Admin Dashboard
You can extend the Medusa Admin to provide merchants with an interface to manage digital products. You can inject widgets into existing pages or create new pages.
Based on your use case, you may need to customize the Medusa Admin to add new widgets or pages.
In your customizations, you send requests to the API routes you created to create and list digital products.
For example, you can create a page that lists all digital products or a widget that allows merchants to view the digital data associated with a product.
The Medusa Admin is an extensible application within your Medusa application. You can customize it by:
- **Widgets**: Adding widgets to existing pages, such as the product page.
- **UI Routes**: Adding new pages to the Medusa Admin, such as a page to manage digital products.
- **Settings Pages**: Adding new pages to the Medusa Admin settings, such as a page to manage digital product settings.
<CardList items={[
{
href: "!docs!/learn/fundamentals/admin/widgets",
title: "Create a Widget",
text: "Learn how to create a widget in the Medusa Admin.",
title: "Create Admin Widget",
text: "Add widgets into existing admin pages.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/admin/ui-routes",
title: "Create UI Route",
text: "Learn how to create a UI route in the Medusa Admin.",
title: "Create Admin UI Routes",
text: "Add new pages to your Medusa Admin.",
icon: AcademicCapSolid,
},
]} />
<Card
href="!docs!/learn/fundamentals/admin/ui-routes#create-settings-page"
title="Create Admin Setting Page"
text="Add new page to the Medusa Admin settings."
icon={AcademicCapSolid}
className="mt-1"
/>
---
## Deliver Digital Products to the Customer
When a customer purchases a digital product, they should receive a link to download it.
You can create or install a fulfillment module provider that handles the logic of fulfilling the digital product.
The Fulfillment Module handles all logic related to fulfilling orders. It also supports using fulfillment module providers that implement the logic of fulfilling orders with third-party services.
<Card
href="/commerce-modules/fulfillment"
title="Fulfillment Module"
text="Learn about the Fulfillment Module and its providers."
icon={AcademicCapSolid}
/>
You can create a custom fulfillment module provider that implements the logic of delivering digital products to customers based on your use case.
<CardList items={[
{
href: "/commerce-modules/fulfillment",
title: "Fulfillment Module",
text: "Learn about the Fulfillment Module.",
icon: AcademicCapSolid,
},
{
href: "/references/fulfillment/provider",
title: "Create Fulfillment Module Provider",
text: "Learn how to create a fulfillment module provider.",
icon: AcademicCapSolid,
},
]} />
---
@@ -194,19 +199,19 @@ Customers use your storefront to browse your digital products and purchase them.
Medusa provides a Next.js Starter Storefront with standard commerce features including listing products, placing orders, and managing accounts. You can customize the storefront and cater its functionalities to support digital products.
Alternatively, you can build the storefront with your preferred tech stack.
Alternatively, you can build your own storefront using the Medusa APIs. This headless approach gives you the flexibility to build a custom storefront without limitations on which tech stack you use, or the design of the storefront.
<CardList items={[
{
href: "/nextjs-starter",
title: "Next.js Starter",
text: "Learn how to install and use the Next.js Starter storefront.",
title: "Next.js Starter Storefront",
text: "Learn how to install and use the Next.js Starter Storefront.",
icon: AcademicCapSolid,
},
{
href: "/storefront-development",
title: "Storefront Guides",
text: "Learn how to build a storefront for your Medusa application.",
text: "Find guides to build your own storefront.",
icon: AcademicCapSolid,
},
]} />

45
www/apps/resources/app/recipes/ecommerce/page.mdx
View File

@@ -16,7 +16,9 @@ Businesses use ecommerce stores to:
- Accept customer orders and payment.
- Manage their store's data and logistics.
Medusa provides all essential commerce features out-of-the-box. Businesses can go live and start selling without making any adjustments. They can also power-up their store by integrating third-party services for payments, fulfillment, and more.
Medusa provides all essential commerce features out-of-the-box. Businesses can go live and start selling without making any adjustments.
Businesses can also power-up their store by integrating third-party services for payments, fulfillment, and more.
<Note title="Related use-case">
@@ -28,7 +30,7 @@ Medusa provides all essential commerce features out-of-the-box. Businesses can g
## Install Ecommerce Store Powered by Medusa
Use the following command to install an ecommerce store with Medusa:
You can use the following command to install an ecommerce store with Medusa:
```bash
npx create-medusa-app@latest --with-nextjs-starter
@@ -37,7 +39,7 @@ npx create-medusa-app@latest --with-nextjs-starter
This installs:
- The Medusa application, which is composed of a Node.js server and a Medusa Admin dashboard. The dashboard opens right after the installation finishes, where you can create a user and start managing your store's data.
- A [Next.js starter storefront](../../nextjs-starter/page.mdx) that connects to your Medusa application to provide customers with ecommerce features.
- A [Next.js Starter Storefront](../../nextjs-starter/page.mdx) that connects to your Medusa application to provide customers with ecommerce features.
---
@@ -45,7 +47,7 @@ This installs:
You can integrate third-party services and tools, customizing the architecture and commerce features of your store.
For example, you can integrate Stripe for payment, or SendGrid for notifications.
For example, you can integrate [Stripe](../../commerce-modules/payment/payment-provider/stripe/page.mdx) to accept payments, or [SendGrid](../../infrastructure-modules/notification/sendgrid/page.mdx) to send emails to customers.
<Card
href="/integrations"
@@ -58,19 +60,36 @@ For example, you can integrate Stripe for payment, or SendGrid for notifications
## Deploy the Medusa Application
Our documentation has step-by-step guides to deploy your Medusa application, Medusa Admin, and the Next.js starter storefront.
The most efficient way to deploy your Medusa application is to use [Medusa Cloud](https://medusajs.com/pricing). Medusa Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Medusa Cloud hosts your server, Admin dashboard, database, and Redis instance.
<Card
href="/deployment"
title="Deployment Guides"
text="Learn how to deploy the Medusa application, Medusa Admin, and Next.js starter storefront."
icon={AcademicCapSolid}
/>
With Medusa Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub:
- Push to deploy.
- Multiple testing environments.
- Preview environments for new PRs.
- Test on production-like data.
Our documentation also provides a step-by-step guides to deploy your Medusa application and the Next.js Starter Storefront.
<CardList itemsPerRow={2} items={[
{
href: "https://medusajs.com/pricing",
title: "Sign up for Medusa Cloud",
text: "Learn more about Medusa Cloud and sign up to get started.",
icon: AcademicCapSolid,
},
{
href: "/deployment",
title: "Deployment Guides",
text: "Learn how to deploy the Medusa application and Next.js Starter Storefront.",
icon: AcademicCapSolid,
},
]} />
---
## Add Custom Features
Along with the extensive ecommerce features, Medusa also provides the architecture and tools to customize and add new features.
Along with the extensive ecommerce features, Medusa also provides the architecture and Framework to customize your application and build custom features that are tailored for your business use case.
To learn how to develop customziations with Medusa, refer to the [Medusa documentation](!docs!/learn)
To learn how to develop customziations with Medusa, refer to the [Get Started](!docs!/learn) documentation.

123
www/apps/resources/app/recipes/marketplace/page.mdx
View File

@@ -17,11 +17,11 @@ This recipe provides the general steps to implement a marketplace in your Medusa
A marketplace is an online commerce store that allows different vendors to sell their products within the same commerce system. Customers can purchase products from any of these vendors, and vendors can manage their orders separately.
In Medusa, you can create a Marketplace Module that implements custom data models, such as vendors or sellers, and link those data models to existing ones such as products and orders. You also expose custom features using API routes, and implement complex flows using workflows.
Medusa's [Framework](!docs!/learn/fundamentals/framework) for customizations facilitates building a marketplace. You can create a Marketplace Module that implements custom data models, such as vendors or sellers, and link those data models to existing ones such as products and orders. You also expose custom features using API routes, and implement complex flows using workflows.
<Note title="Related use-case">
[How Goodchef built subscription-based purchases with Medusa](https://medusajs.com/blog/foraged/).
[How Foraged built a custom marketplace with Medusa](https://medusajs.com/blog/foraged/).
</Note>
@@ -31,7 +31,7 @@ In Medusa, you can create a Marketplace Module that implements custom data model
In a marketplace, a business or a vendor has a user, and they can use that user to authenticate and manage the vendor's data.
You can create a marketplace module that implements data models for vendors, their admins, anything else that fits your use case.
You can create a marketplace module that implements data models for vendors, their admins, and any other data models that fits your use case.
<CardList items={[
{
@@ -50,11 +50,11 @@ You can create a marketplace module that implements data models for vendors, the
---
## Define Module Links
## Link Custom and Existing Data Models
Since a vendor has products, orders, and other models based on your use case, define module links between your module's data models and the Commerce Module's data models.
Since a vendor has products, orders, and other models based on your use case, you can define module links between your module's data models and the Commerce Module's data models.
For example, if you defined a vendor data model in a marketplace module, you can define a module link between the vendor and the Product Module's product data model.
For example, if you defined a vendor data model in a marketplace module, you can define a module link between the vendor and the Product Module's product data model. This builds an association between a vendor and their products, allowing you to query and manage products based on the vendor.
<Card
href="!docs!/learn/fundamentals/module-links"
@@ -65,24 +65,13 @@ For example, if you defined a vendor data model in a marketplace module, you can
---
## Allow Vendor Admins to Authenticate
If your marketplace module implements admins for sellers or vendors, you can create an actor type for it.
Then, you guard custom API routes to only allow authenticated vendor admins.
<Card
href="/commerce-modules/auth/create-actor-type"
title="Create an Actor Type"
text="Learn how to create an actor type and authenticate it."
icon={AcademicCapSolid}
/>
---
## Create Vendor API Routes
If you provide vendor or sellers with custom features, or a different way of managing products and orders, create API routes only accessible by vendors exposing your custom features.
Your marketplace will most likely provide custom features for vendors, such as managing their products and orders. You can create API routes that expose these features to the vendors.
When you build these API routes, it's essential that you protect them to only allow authenticated vendors. For example, only a vendor's admin should be able to manage their products and orders.
Medusa supports creating custom actor types that can be authenticated with your custom API routes.
<CardList items={[
{
@@ -92,9 +81,9 @@ If you provide vendor or sellers with custom features, or a different way of man
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/api-routes/protected-routes",
title: "Protect Routes",
text: "Learn how to guard routes to allow authenticated users only.",
href: "/commerce-modules/auth/create-actor-type",
title: "Create an Actor Type",
text: "Learn how to create an actor type and authenticate it.",
icon: AcademicCapSolid,
},
]} />
@@ -103,24 +92,84 @@ If you provide vendor or sellers with custom features, or a different way of man
## Split Orders Based on Vendors
If your use case allows a customer's orders to have items from different vendors, you can override the [Complete Cart API route](!api!/store#carts_postcartsidcomplete) to change how the order should be created.
If your use case allows a customer's orders to have items from different vendors, you can replicate the [Complete Cart API route](!api!/store#carts_postcartsidcomplete) to customize the order creation process.
If your flow requires different steps, such as creating a parent order then creating a child order, create a workflow and execute it from the API route.
In the API route, you can create a workflow that splits the order into multiple orders, one for each vendor. A workflow is a series of steps that provide features like rollback and retry mechanisms.
<CardList items={[
{
href: "!docs!/learn/fundamentals/api-routes/override",
title: "Replicate API Routes",
text: "Learn how to replicate an existing API route.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/workflows",
title: "Create a Workflow",
text: "Learn how to create a workflow in Medusa.",
icon: AcademicCapSolid,
},
]} />
---
## Customize Admin Dashboard
Based on your use case, you may need to customize the Medusa Admin to add new widgets or pages.
For example, you can create a page that lists all vendors or a widget that shows a product's vendor information.
The Medusa Admin is an extensible application within your Medusa application. You can customize it by:
- **Widgets**: Adding widgets to existing pages, such as the product page.
- **UI Routes**: Adding new pages to the Medusa Admin, such as a page to manage vendors.
- **Settings Pages**: Adding new pages to the Medusa Admin settings, such as a page to manage marketplace settings.
<CardList items={[
{
href: "!docs!/learn/fundamentals/admin/widgets",
title: "Create Admin Widget",
text: "Add widgets into existing admin pages.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/admin/ui-routes",
title: "Create Admin UI Routes",
text: "Add new pages to your Medusa Admin.",
icon: AcademicCapSolid,
},
]} />
<Card
href="!docs!/learn/fundamentals/workflows"
title="Create a Workflow"
text="Learn how to create a workflow in Medusa."
href="!docs!/learn/fundamentals/admin/ui-routes#create-settings-page"
title="Create Admin Setting Page"
text="Add new page to the Medusa Admin settings."
icon={AcademicCapSolid}
className="mt-1"
/>
---
## Build Dashbord for Vendors
For more complex use cases, customizing the Medusa Admin may not be enough to allow vendors to manage their data.
In that case, you can build a custom dashboard for vendors that allows them to manage their data. This dashboard can interact with Medusa's Admin API and the custom API routes you created for vendors to provide a seamless experience.
<Card
href="!api!/admin"
title="Medusa Admin APIs"
text="Learn about available APIs for the Medusa Admin."
icon={AcademicCapSolid}
/>
---
## Customize Storefront
## Customize or Build Storefront
Medusa provides a Next.js Starter storefront that you can customize for your use case.
Medusa provides a Next.js Starter Storefront to use with your application. You can customize it to for your marketplace use case, such as showing products by vendor.
You can also create a custom storefront from scratch.
Alternatively, you can build your own storefront using the Medusa APIs. This headless approach gives you the flexibility to build a custom storefront without limitations on which tech stack you use, or the design of the storefront.
<CardList items={[
{
@@ -136,11 +185,3 @@ You can also create a custom storefront from scratch.
icon: AcademicCapSolid,
},
]} />
---
## Customize Admin
The Medusa Admin is extendable, allowing you to add widgets to existing pages or create new pages.
If your use case requires bigger customizations to the admin, such as showing different products and orders based on the logged-in vendor, use the [admin API routes](!api!/admin) to build a custom admin.

36
www/apps/resources/app/recipes/multi-region-store/page.mdx
View File

@@ -49,13 +49,15 @@ During checkout, Medusa calculates the taxes using the tax region settings of th
### Payment and Fulfillment Providers
Merchants choose which payment providers are available in each region. For example, one region can use Payment Provider A and B while another only uses Payment Provider B. Merchants can also choose the fulfillment providers available in each stock location, and provide shipping options using the providers in those locations.
Merchants choose which payment providers are available in each region. For example, one region can use Payment Provider A and B while another only uses Payment Provider B.
Merchants can also choose the fulfillment providers available in each stock location, and provide shipping options using the providers in those locations.
During checkout, customers only see the payment providers configured for the region, and they can only choose shipping options that can be used to fulfill items to their shipping address. This allows merchants to give customers a localized experience that feels familiar and instills trust.
Medusa provides official module providers for payment and fulfillment. You can also create custom module providers.
<CardList items={[
<CardList itemsPerRow={2} items={[
{
href: "!user-guide!/settings/regions",
title: "Manage Payment Providers in Medusa Admin",
@@ -68,22 +70,26 @@ Medusa provides official module providers for payment and fulfillment. You can a
text: "Learn how to manage providers in a location.",
icon: UsersSolid,
},
{
href: "/integrations",
title: "Integrations",
text: "Check out available integrations, including payment module providers.",
icon: AcademicCapSolid
},
{
href: "/references/fulfillment/provider",
title: "Create Fulfillment Module Provider",
text: "Learn how to create a fulfillment module provider.",
icon: AcademicCapSolid,
}
]} />
<Card
href="/integrations"
title="Integrations"
text="Check out available integrations, including payment module providers."
icon={AcademicCapSolid}
className="mt-1"
/>
---
## Prices Per Region and Currency
Merchants set the price of a product's variants per currency and region. This also applies to adding sales or overriding prices for specific conditions.
Merchants set the price of shipping options and product variants per currency and region. This also applies to adding sales or overriding prices for specific conditions.
Using the tax-inclusive feature, merchants can also specify prices including taxes per currency and region. Medusa then calculates the tax amount applied to a line item in the cart based on the region's tax configurations.
@@ -131,7 +137,7 @@ A multi-regional setup lets merchants manage their inventory through Medusa acro
By integrating a third-party Content Management Systems (CMS), you benefit from rich content features including managing your content in multiple languages. This allows you to cater to customers’ different languages in the regions you serve.
To integrate a third-party system, create a custom module whose main service connects to that third-party service. You can also follow the [Sanity integration guide](../../integrations/guides/sanity/page.mdx) to integrate Sanity with Medusa.
To integrate a third-party system, create a custom module whose main service connects to that third-party service. You can also follow the [Contentful integration guide](../../integrations/guides/contentful/page.mdx) to learn how to integrate Contentful and benefit from localization features.
<CardList items={[
{
@@ -141,9 +147,9 @@ To integrate a third-party system, create a custom module whose main service con
icon: AcademicCapSolid,
},
{
href: "/integrations/guides/sanity",
title: "Integrate Sanity",
text: "Follow a step-by-step guide to integrate Sanity.",
href: "/integrations/guides/contentful",
title: "Integrate Contentful",
text: "Integrate Contentful with Localization Features.",
icon: AcademicCapSolid,
},
]} />

33
www/apps/resources/app/recipes/omnichannel/page.mdx
View File

@@ -39,11 +39,13 @@ Businesses are no longer bound to sell in their stores. They can reach their cus
One example is marketplaces like Amazon. Customers searching through Amazon to find products are inadvertently searching through many third-party stores connected to Amazon’s marketplace.
You can implement this example in Medusa with the Sales Channel Module and a custom module. Use the Sales Channel Module's features to set different product availability across sales channels. Then, in the custom module, integrate with Amazon’s seller program and use their APIs to push your products on Amazon.
You can implement this example in Medusa with the Sales Channel Module and a custom module. Use the Sales Channel Module's features to set different product availability across sales channels.
Then, in the custom module, integrate with Amazon’s seller program. You can then build workflows that sync your products with Amazon’s marketplace.
Another channel that attracts customer sales is social media. You can create a custom module that integrates with social media apps to show your products and sell them to customers.
<CardList itemsPerRow={2} items={[
<CardList items={[
{
href: "/commerce-modules/sales-channel",
title: "Sales Channels",
@@ -58,6 +60,14 @@ Another channel that attracts customer sales is social media. You can create a c
},
]} />
<Card
href="!docs!/learn/fundamentals/workflows#1-create-workflow"
title="Create a Workflow"
text="Learn how to create a workflow."
icon={AcademicCapSolid}
className="mt-1"
/>
---
## Optimize Customer Experience
@@ -67,10 +77,11 @@ Implement the customer journey and design for your storefronts that leads to the
Medusa’s architecture also makes it easier to integrate any third-party services to provide a better customer experience:
- Create a module that integrates the third-party service.
- Expose the module's features in API routes.
- Build a workflow that performs actions spanning across the third-party service and your Medusa application.
- Expose the workflow's features in API routes.
- Send requests to these API routes from your storefront.
<CardList itemsPerRow={2} items={[
<CardList items={[
{
href: "!docs!/learn/fundamentals/modules",
title: "Create a Module",
@@ -78,9 +89,17 @@ Medusa’s architecture also makes it easier to integrate any third-party servic
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/api-routes",
title: "Create an API Route",
text: "Learn how to create an API route.",
href: "!docs!/learn/fundamentals/workflows",
title: "Create a Workflow",
text: "Learn how to create a workflow.",
icon: AcademicCapSolid,
},
]} />
<Card
href="!docs!/learn/fundamentals/api-routes"
title="Create API Route"
text="Learn how to create an API route."
icon={AcademicCapSolid}
className="mt-1"
/>

40
www/apps/resources/app/recipes/oms/page.mdx
View File

@@ -13,7 +13,7 @@ This recipe provides an overview of Medusa's features and how to use it as an Or
Building or integrating an OMS brings certain challenges: accepting orders from different sales channels, tracking inventory across the sales channels, integrating third-party fulfillment and payment providers with the OMS, and more.
Medusa's Commerce Modules and customization toolkit lets you integrate it within a larger ecosystem. The Commerce Modules provide features to allow businesses to accept orders from any sales channel, benefit from multi-warehouse inventory features, and integrate third-party services for fulfillment, payment, and more.
Medusa's Commerce Modules and [Framework](!docs!/learn/fundamentals/framework) for customizations allows you to integrate it within a larger ecosystem. The Commerce Modules provide features to allow businesses to accept orders from any sales channel, benefit from multi-warehouse inventory features, and integrate third-party services for fulfillment, payment, and more.
<Note title="Related use-case">
@@ -62,13 +62,13 @@ For example, you can support importing orders into Medusa through a custom API R
## Route Orders to Third-party Fulfillment Services
To integrate third-party fulfillment providers with the Medusa application, create a fulfillment module provider.
To integrate third-party fulfillment providers with the Medusa application, you can create a fulfillment module provider.
Medusa uses the Fulfillment Module whenever a fulfillment action is performed, such as when a fulfillment is created for items in an order. The module's main service's methods use the associated fulfillment module provider to handle the desired fulfillment actions.
Medusa uses the Fulfillment Module whenever a fulfillment action is performed, such as when a fulfillment is created for items in an order. The methods of the module's main service use the associated fulfillment module provider to handle the desired fulfillment actions.
![Fulfilling orders with Medusa OMS](https://res.cloudinary.com/dza7lstvk/image/upload/v1709032184/Medusa%20Book/oms-fulfillment_qfrpdd.jpg)
In addition, create a subscriber that listen to fulfillment-related events, such as the `order.fulfillment_created` event, to perform actions with the third-party fulfillment provider.
In addition, you can create a subscriber that listens to fulfillment-related events, such as the `order.fulfillment_created` event, to perform actions with the third-party fulfillment provider.
<CardList itemsPerRow={2} items={[
{
@@ -97,9 +97,9 @@ In addition, create a subscriber that listen to fulfillment-related events, such
## Process Payment with Third-Party Providers
To integrate third-party payment providers with the Medusa application, create a payment module provider.
To integrate third-party payment providers with the Medusa application, you can create a payment module provider. Customers can pay for their orders using this providers, and admins can process order payments using it.
In addition, create a subscriber that listen to payment-related events, such as the `payment.captured` event, to perform actions in the third-party payment provider.
In addition, you can create a subscriber that listen to payment-related events, such as the `payment.captured` event, to perform actions in the third-party payment provider.
<CardList itemsPerRow={2} items={[
{
@@ -130,7 +130,9 @@ In addition, create a subscriber that listen to payment-related events, such as
Medusa's Inventory, Stock Location, and Sales Channel modules allow merchants to track inventory levels tied to sales channels across stock locations.
When an order is placed, the item's quantity is reserved from the stock location associated with the order's sales channel. Once the item is fulfilled, the reserved quantity is deducted from the item's inventory quantity.
When an order is placed, the item's quantity is reserved from the stock location associated with the order's sales channel.
Once the item is fulfilled, the reserved quantity is deducted from the item's inventory quantity.
<CardList items={[
{
@@ -159,11 +161,11 @@ When an order is placed, the item's quantity is reserved from the stock location
## Handle Returns, Exchanges, and Changes
In Medusa, items in an order can be returned or exchanged. A merchant can also edit an order to add, update, or delete items.
Customers can return or exchaneg items in an order. A merchant can also edit an order to add, update, or delete items.
When changes are made to an order by any of the mentioned actions, the changes are reflected on the order's totals and associated inventory. The integrated fulfillment and payment module providers are used if fulfillment or payment actions are required, such as fulfilling exchanged items.
Medusa also emits events related to these actions, such as `order.return_requested`. So, you can create a subscriber that listens to these events and perform asynchronous actions, such as communicating with third-party services.
Medusa also emits events related to these actions, such as `order.return_requested`. So, you can build a workflow that performs actions with the third-party fulfillment and payment providers, then execute it in a subscriber that's triggered whenever the event is emitted.
<CardList items={[
{
@@ -178,12 +180,16 @@ Medusa also emits events related to these actions, such as `order.return_request
text: "Learn about the events emitted related to the Order Module",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/workflows",
title: "Create a Workflow",
text: "Learn how to create a workflow.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/events-and-subscribers",
title: "Create a Subscriber",
text: "Learn about create a subscriber",
icon: AcademicCapSolid,
}
]} />
<Card
href="!docs!/learn/fundamentals/events-and-subscribers"
title="Create a Subscriber"
text="Learn about create a subscriber"
icon={AcademicCapSolid}
className="mt-1"
/>

90
www/apps/resources/app/recipes/page.mdx
View File

@@ -1,4 +1,19 @@
import { ChildDocs } from "docs-ui"
import { CardList } from "docs-ui"
import {
BuildingStorefront,
CalendarSolid,
PhotoSolid,
ChannelsSolid,
BuildingsSolid,
GiftSolid,
ClockSolid,
ShoppingCartSolid,
GlobeEuropeSolid,
Phone,
HandTruck,
PenPlus,
Receipt
} from "@medusajs/icons"
export const metadata = {
title: `Recipes`,
@@ -8,4 +23,75 @@ export const metadata = {
This section of the documentation provides recipes for common use cases with example implementations.
<ChildDocs onlyTopLevel hideItems={["Overview"]} />
## Recipes
<CardList
itemsPerRow={2}
items={[
{
href: "/recipes/marketplace",
title: "Marketplace",
icon: BuildingStorefront,
},
{
href: "/recipes/subscriptions",
title: "Subscriptions",
icon: CalendarSolid,
},
{
href: "/recipes/digital-products",
title: "Digital Products",
icon: PhotoSolid,
},
{
href: "/recipes/erp",
title: "Integrate ERP",
icon: ChannelsSolid,
},
{
href: "/recipes/b2b",
title: "B2B",
icon: BuildingsSolid,
},
{
href: "/recipes/bundled-products",
title: "Bundled Products",
icon: GiftSolid,
},
{
href: "/recipes/commerce-automation",
title: "Commerce Automation",
icon: ClockSolid,
},
{
href: "/recipes/ecommerce",
title: "Ecommerce",
icon: ShoppingCartSolid,
},
{
href: "/recipes/multi-region-store",
title: "Multi-Region Store",
icon: GlobeEuropeSolid,
},
{
href: "/recipes/omnichannel",
title: "Omnichannel Store",
icon: Phone,
},
{
href: "/recipes/oms",
title: "OMS",
icon: HandTruck,
},
{
href: "/recipes/personalized-products",
title: "Personalized Products",
icon: PenPlus,
},
{
href: "/recipes/pos",
title: "POS",
icon: Receipt,
}
]}
/>

53
www/apps/resources/app/recipes/personalized-products/page.mdx
View File

@@ -12,7 +12,7 @@ This recipe provides the general steps to build personalized products in Medusa.
Personalized products are products that customers can customize based on their need. For example, they can upload an image to print on a shirt or provide a message to include in a letter.
In Medusa, you create a custom module defining data models, implementing custom features, and creating relationships to other modules' data models.
In Medusa, you can create a custom module defining data models related to personalization with the service to manage them. Then, you can link those data models to existing data models, such as products.
You also have freedom in how you choose to implement the storefront, allowing you to build a unique experience around your products.
@@ -68,19 +68,19 @@ Medusa's modular architecture removes any restrictions on the your storefront's
You can build a unique experience around your products that focuses on the customer’s personalization capabilities.
Medusa provides a Next.js Starter storefront with basic ecommerce functionalities that can be customized. You can also build your own storefront and use Medusa’s client libraries or Store API Routes to communicate with the Medusa application.
Medusa provides a Next.js Starter Storefront with basic ecommerce functionalities that can be customized. You can also build your own storefront and use Medusa’s client libraries or Store API Routes to communicate with the Medusa application.
<CardList itemsPerRow={2} items={[
{
href: "/nextjs-starter",
title: "Next.js Starter",
text: "Learn about the Next.js Starter and how to install it.",
title: "Next.js Starter Storefront",
text: "Learn how to install the Next.js Starter Storefront.",
icon: NextJs,
},
{
href: "/storefront-development",
title: "Storefront Development",
text: "Find guides for your storefront development.",
text: "Find guides to build your own storefront.",
icon: AcademicCapSolid,
},
]} />
@@ -89,13 +89,20 @@ Medusa provides a Next.js Starter storefront with basic ecommerce functionalitie
## Pass Personalized Data to the Order
If you store the personalized data using a custom module:
If you store the personalized data using a custom module, you can:
- Create a custom API Route that handles saving the personalization data.
- Create a workflow that handles saving the personalization data.
- Create a custom API Route that executes the workflow.
- Call that API Route from the storefront after adding the item to the cart.
- Listen to the `order.placed` event to attach the personalized data to the Order Module's `LineItem` data model.
- Consume the `orderCreated` hook of the [completeCartWorkflow](/references/medusa-workflows/completeCartWorkflow) to attach the personalized data to the Order Module's `LineItem` data model.
<CardList items={[
{
href: "!docs!/learn/fundamentals/workflows",
title: "Create a Workflow",
text: "Learn how to create a workflow.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/api-routes",
title: "Create API Route",
@@ -103,9 +110,9 @@ If you store the personalized data using a custom module:
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/events-and-subscribers",
title: "Create a Subscriber",
text: "Learn how to create a subscriber.",
href: "!docs!/learn/fundamentals/workflows/workflow-hooks",
title: "Consume a Hook",
text: "Learn how to create a hook.",
icon: AcademicCapSolid,
},
]} />
@@ -114,13 +121,23 @@ If you store the personalized data using a custom module:
## Fulfill Personalized Products in Orders
To fulfill your personalized products with a third-party service or custom logic, create a fulfillment module provider.
The Fulfillment Module handles all logic related to fulfilling orders. It also supports using fulfillment module providers that implement the logic of fulfilling orders with third-party services.
To fulfill your personalized products with a third-party service or custom logic, you can create a fulfillment module provider.
The Fulfillment Module registers your fulfillment module provider to use it to fulfill orders.
<Card
href="/references/fulfillment/provider"
title="Create a Fulfillment Provider"
text="Learn how to create a fulfillment provider in Medusa."
icon={AcademicCapSolid}
/>
<CardList items={[
{
href: "/commerce-modules/fulfillment",
title: "Fulfillment Module",
text: "Learn about the Fulfillment Module.",
icon: AcademicCapSolid,
},
{
href: "/references/fulfillment/provider",
title: "Create Fulfillment Module Provider",
text: "Learn how to create a fulfillment module provider.",
icon: AcademicCapSolid,
},
]} />

33
www/apps/resources/app/recipes/pos/page.mdx
View File

@@ -24,9 +24,9 @@ Medusa's modular architecture solves these challenges. Any frontend can utilize
## Freedom in Choosing Your POS Tech Stack
When you build a POS system, you must choose the programming language or tool you want to use.
When you build a POS system, you choose the programming language or tool you want to use.
Medusa's modular architecture removes any restrictions you may have while making this choice. Any client or front end can connect to the Medusa application using its headless REST APIs.
Medusa's modular architecture removes any restrictions you may have while making this choice. Any client or frontend can connect to the Medusa application using its headless REST APIs.
![POS Tech Stack](https://res.cloudinary.com/dza7lstvk/image/upload/v1709034046/Medusa%20Book/pos-tech-stack_fy8uiu.jpg)
@@ -43,7 +43,7 @@ Medusa's modular architecture removes any restrictions you may have while making
POS systems make the checkout process smoother by integrating a barcode scanner. Merchants scan a product by its barcode to check its details or add it to the customer's purchase.
The Product Module's `ProductVariant` data model has the properties to implement this integration, mainly the `barcode` attribute. Other notable properties include `ean`, `upc`, and `hs_code`, among others.
The Product Module's [ProductVariant](/references/product/models/ProductVariant) data model has the properties to implement this integration, mainly the `barcode` attribute. Other notable properties include `ean`, `upc`, and `hs_code`, among others.
To search through product variants by their barcode, create a custom API Route and call it within your POS.
@@ -79,7 +79,9 @@ Medusa's [Inventory](../../commerce-modules/inventory/page.mdx), [Stock Location
Merchants can create a sales channel for their online store and a sales channel for their POS system, then manage the inventory quantity of product variants in each channel.
This also opens the door for other business opportunities, such as an endless aisle experience. Suppose a product isn't available in-store but is available in different warehouses. You can allow customers to purchase that item in-store and deliver it to their address.
This also opens the door for other business opportunities, such as an endless aisle experience.
Suppose a product isn't available in-store but is available in different warehouses. You can allow customers to purchase that item in-store and deliver it to their address.
<CardList
items={[
@@ -117,7 +119,14 @@ In addition, using Medusa's [Promotion Module](../../commerce-modules/promotion/
You can also create custom modules to provide features for a better customer experience, such as a rewards system or loyalty points.
<CardList
itemsPerRow={2}
items={[
{
href: "/how-to-tutorials/tutorials/loyalty-points",
title: "Loyalty Points Tutorial",
text: "Learn how to create a loyalty points system.",
icon: AcademicCapSolid,
},
{
href: "/commerce-modules/customer",
title: "Customer Module",
@@ -130,24 +139,22 @@ You can also create custom modules to provide features for a better customer exp
text: "Learn about the Promotion Module.",
icon: AcademicCapSolid,
},
{
href: "!docs!/learn/fundamentals/modules",
title: "Create a Module",
text: "Learn how to create a module.",
icon: AcademicCapSolid,
}
]}
/>
<Card
href="!docs!/learn/fundamentals/modules"
title="Create a Module"
text="Learn how to create a module."
icon={AcademicCapSolid}
className="mt-1"
/>
---
## Accept Payment, Place Order, and Use RMA Features
Medusa's architecture allows you to integrate any third-party payment provider for your POS and online storefront. For example, you can integrate [Stripe Terminal](https://stripe.com/terminal) to accept in-store payments.
Once you accept the payment, place an order in the POS system using the [Draft Order APIs](!api!/admin#draft-orders). Draft orders provide similar features to an online checkout experience, including discounts, payment processing, and more.
Once you accept the payment, you can place an order in the POS system using the [Draft Order APIs](!api!/admin#draft-orders). Draft orders provide similar features to an online checkout experience, including discounts, payment processing, and more.
Then, merchants can view all orders coming from different sales channels using the Medusa Admin. This keeps logistics and order handling consistent between online and in-store customers.

77
www/apps/resources/app/recipes/subscriptions/page.mdx
View File

@@ -14,6 +14,10 @@ Subscription-based purchase allows customers to purchase products for a specifie
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.
Medusa's [Framework](!docs!/learn/fundamentals/framework) for customizations facilitates building subscription-based purchases. You can create a Subscription Module that implements data models for subscriptions, and link those data models to existing ones such as products and orders.
You can also expose custom features using API routes, and implement complex flows using workflows.
<Note title="Related use-case">
[How Goodchef built subscription-based purchases with Medusa](https://medusajs.com/blog/goodchef/).
@@ -26,7 +30,7 @@ For example, a customer can purchase a book subscription box for a period of thr
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.
To store the subscription details, you can 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.
@@ -47,7 +51,7 @@ You can link the subscription data model to models of other modules, such as the
---
## Define Module Links
## Link Subscription to Existing Data Models
Define a module link that links a data model from your subscription module with a data model from another module.
@@ -74,32 +78,41 @@ By implementing the subscription logic within your application, you have full co
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.
1. Create a workflow that completes a cart and creates a subscription for the order.
1. Create an API route that executes the workflow.
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/workflows",
title: "Create a Workflow",
text: "Learn how to create a workflow.",
icon: AcademicCapSolid,
},
{
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,
}
]} />
<Card
href="!docs!/learn/fundamentals/scheduled-jobs#1-create-a-scheduled-job"
title="Create a Scheduled Job"
text="Learn how to create a scheduled job."
icon={AcademicCapSolid}
className="mt-1"
/>
### 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.
Although Medusa provides a [Stripe Payment Module Provider](../../commerce-modules/payment/payment-provider/stripe/page.mdx), it doesn't handle subscriptions. You can create a custom Stripe Subscription Module Provider instead.
<Card
href="/references/payment/provider"
@@ -110,44 +123,60 @@ Although Medusa provides a Stripe module provider, it doesn't handle subscriptio
---
## Customize Admin
## Customize Admin Dashboard
You can extend the admin to provide an interface to manage your custom features, such as view the subscriptions.
Based on your use case, you may need to customize the Medusa Admin to add new widgets or pages.
Extend the Medusa Admin to add widgets to existing pages or add new pages.
For example, you can create a page that lists all subscriptions or a widget that shows an order's subscription information.
The Medusa Admin is an extensible application within your Medusa application. You can customize it by:
- **Widgets**: Adding widgets to existing pages, such as the order page.
- **UI Routes**: Adding new pages to the Medusa Admin, such as a page to manage subscriptions.
- **Settings Pages**: Adding new pages to the Medusa Admin settings, such as a page to manage subscription settings.
<CardList items={[
{
href: "!docs!/learn/fundamentals/admin/widgets",
title: "Create Admin Widget",
text: "Learn how to add widgets into existing admin pages.",
text: "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.",
text: "Add new pages to your Medusa Admin.",
icon: AcademicCapSolid,
}
},
]} />
<Card
href="!docs!/learn/fundamentals/admin/ui-routes#create-settings-page"
title="Create Admin Setting Page"
text="Add new page to the Medusa Admin settings."
icon={AcademicCapSolid}
className="mt-1"
/>
---
## Build a Storefront
## Customize or Build 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.
Medusa provides a Next.js Starter Storefront to use with your application. You can customize it to for your subscription use case, such as allowing customers to manage their subscriptions.
Alternatively, you can build your own storefront using the Medusa APIs. This headless approach gives you the flexibility to build a custom storefront without limitations on which tech stack you use, or the design of the storefront.
<CardList items={[
{
href: "/nextjs-starter",
title: "Option 1: Use Next.js Starter",
text: "Install the Next.js Starter to customize it.",
title: "Next.js Starter Storefront",
text: "Learn how to install and customize the Next.js Starter Storefront.",
icon: AcademicCapSolid,
},
{
href: "/storefront-development",
title: "Option 2: Build Custom Storefront",
text: "Find guides for your storefront development.",
title: "Storefront Development",
text: "Find guides to build your own storefront.",
icon: AcademicCapSolid,
}
]} />
},
]} />

24
www/apps/resources/generated/edit-dates.mjs
View File

@@ -109,21 +109,21 @@ export const generatedEditDates = {
"app/medusa-container-resources/page.mdx": "2025-04-17T08:48:10.255Z",
"app/medusa-workflows-reference/page.mdx": "2025-01-20T08:21:29.962Z",
"app/nextjs-starter/page.mdx": "2025-02-26T11:37:47.137Z",
"app/recipes/b2b/page.mdx": "2025-04-17T08:48:38.369Z",
"app/recipes/commerce-automation/page.mdx": "2025-05-01T15:33:47.062Z",
"app/recipes/b2b/page.mdx": "2025-05-16T10:31:09.977Z",
"app/recipes/commerce-automation/page.mdx": "2025-05-16T10:56:44.002Z",
"app/recipes/digital-products/examples/standard/page.mdx": "2025-04-24T15:41:05.364Z",
"app/recipes/digital-products/page.mdx": "2025-04-30T12:19:20.550Z",
"app/recipes/ecommerce/page.mdx": "2025-02-26T12:20:52.092Z",
"app/recipes/digital-products/page.mdx": "2025-05-16T11:07:00.720Z",
"app/recipes/ecommerce/page.mdx": "2025-05-16T11:12:32.215Z",
"app/recipes/marketplace/examples/vendors/page.mdx": "2025-05-13T15:14:31.606Z",
"app/recipes/marketplace/page.mdx": "2025-04-17T08:48:36.942Z",
"app/recipes/multi-region-store/page.mdx": "2025-02-26T12:38:50.292Z",
"app/recipes/omnichannel/page.mdx": "2025-02-26T12:22:08.331Z",
"app/recipes/oms/page.mdx": "2025-04-17T08:48:35.570Z",
"app/recipes/personalized-products/page.mdx": "2025-02-26T12:41:48.547Z",
"app/recipes/pos/page.mdx": "2025-02-26T12:42:52.949Z",
"app/recipes/marketplace/page.mdx": "2025-05-16T11:25:20.087Z",
"app/recipes/multi-region-store/page.mdx": "2025-05-16T11:38:41.971Z",
"app/recipes/omnichannel/page.mdx": "2025-05-16T11:43:24.164Z",
"app/recipes/oms/page.mdx": "2025-05-16T11:48:45.638Z",
"app/recipes/personalized-products/page.mdx": "2025-05-16T11:59:29.086Z",
"app/recipes/pos/page.mdx": "2025-05-16T12:03:58.916Z",
"app/recipes/subscriptions/examples/standard/page.mdx": "2025-05-13T15:18:51.247Z",
"app/recipes/subscriptions/page.mdx": "2025-02-26T12:31:49.933Z",
"app/recipes/page.mdx": "2025-03-07T07:48:28.203Z",
"app/recipes/subscriptions/page.mdx": "2025-05-16T12:09:12.912Z",
"app/recipes/page.mdx": "2025-05-16T12:20:18.488Z",
"app/service-factory-reference/methods/create/page.mdx": "2024-07-31T17:01:33+03:00",
"app/service-factory-reference/methods/delete/page.mdx": "2024-07-31T17:01:33+03:00",
"app/service-factory-reference/methods/list/page.mdx": "2024-07-31T17:01:33+03:00",