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

docs: updated recipes (#5138)

Browse Source
This commit is contained in:
Shahed Nasser
2023-09-19 13:48:27 +03:00
committed by GitHub
parent 5b557d3098
commit d709521826
8 changed files with 212 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
www/docs/content/recipes/b2b.mdx
View File

@@ -13,12 +13,9 @@ This document guides you through the different documentation resources that will
## Overview
In a B2B store, the seller provides other businesses with wholesale products and prices. Medusa allows you to build a B2B store in different ways:
In a B2B store, it’s essential to differentiate between customer types to provide them with relevant pricing, products, shopping experience, and more.
1. **Fully B2B:** You can use Medusa as-is and cater to businesses only. You can also specify different pricing for different businesses using [Customer Groups](../user-guide/customers/groups.mdx) and [Price Lists](../user-guide/price-lists/index.md).
2. **B2B and B2C:** You can serve both businesses and customers within the same store, supplying different products or prices for each.
This recipe covers the high-level steps to implement the second case, a B2B and B2C store.
Medusa’s commerce features, including sales channels, customer groups, and price lists, facilitate implementing this setup. Medusa’s architecture and extendible nature allow you to customize your store based on your use case.
<LearningPath pathName="b2b" />
@@ -26,9 +23,9 @@ This recipe covers the high-level steps to implement the second case, a B2B and
## Create B2B Sales Channel
In Medusa, a sales channel allows you to set product availability per channel. In this case, you can create a B2B sales channel that will include only your wholesale products.
In Medusa, a sales channel allows you to set product availability per channel. In this case, you can create a B2B sales channel that will include only B2B products.
You can create a sales channel either through the Medusa admin or through the Admin REST APIs.
You can create a sales channel through the Medusa admin or Admin REST APIs.
<DocCardList colSize={6} items={[
{
@@ -57,7 +54,7 @@ You can create a sales channel either through the Medusa admin or through the Ad
Publishable API keys can be associated with one or more sales channels. Then, in a client such as a storefront, you can pass the publishable API key in the header of your requests to ensure all products retrieved belong to the associated sales channel(s).
You can create a publishable API key either through the Medusa admin or through the Admin REST APIs.
You can create a publishable API key through the Medusa admin or the Admin REST APIs, then associate it with the B2B sales channel. You’ll later use this key when developing your B2B storefront.
<DocCardList colSize={6} items={[
{
@@ -82,11 +79,11 @@ You can create a publishable API key either through the Medusa admin or through
---
## Add Wholesale Products
## Add Products
Using the Medusa admin or the Admin REST APIs, you can add your wholesale products to your store. You can also use the Product Import feature to import your products from an existing CSV file.
Using the Medusa admin or the Admin REST APIs, you can add your B2B products to your store. You can also import your products from an existing CSV file using the Product Import feature.
After or while you add your products, make sure to set the products’ availability to the B2B sales channel you’ve created.
After or while you add your products, set the products’ availability to the B2B sales channel you’ve created.
<DocCardList colSize={6} items={[
{
@@ -131,13 +128,13 @@ After or while you add your products, make sure to set the products’ availabil
## Create B2B Customer Groups
To apply different prices for your B2B customers, you need to create a customer group that indicates this customer is a B2B customer.
In B2B sales, you often negotiate special prices with each customer or company. So, you need to organize your B2B customers into groups that allow you to set different prices for each.
You can either create a single B2B customer group that all your B2B customers will fall into, or you can create different B2B customer groups for every B2B customer. The second approach is useful if you want to apply different prices for different businesses.
You can create a single B2B customer group that all your B2B customers will fall into or create different B2B customer groups for every B2B customer. The second approach is helpful if you apply different prices for each business.
While you’re creating the customer groups, make sure to add the `metadata` of the customer group a key `is_b2b` that acts as a flag to indicate that this is a B2B customer group. This is useful for later steps.
While creating the customer groups, make sure to add to the `metadata` attribute of the customer group a key `is_b2b` that acts as a flag to indicate that this is a B2B customer group. This is useful for later steps.
Alternatively, you may choose to create custom entities or a different mechanism that indicates a customer is a B2B customer. This is covered in the [Create Custom Entities section](#create-custom-entities).
For more advanced customer modeling, you may create custom entities. This is covered in the [Create Custom Entity section](#create-custom-entity).
<DocCardList colSize={6} items={[
{
@@ -164,9 +161,9 @@ Alternatively, you may choose to create custom entities or a different mechanism
## Add B2B Customers
After adding your B2B customer group, you can add B2B customers and assign them to the B2B customer group. Alternatively, if you want to allow B2B customers to register themselves, you can implement that logic within your storefront.
After adding your B2B customer group, you can add B2B customers and assign them to the B2B customer group. Alternatively, if you want to allow B2B customers to register themselves, then that will be covered in a later step.
You can create a customer either through the Medusa admin or Admin REST APIs.
You can create a customer through the Medusa admin or Admin REST APIs.
<DocCardList colSize={6} items={[
{
@@ -193,11 +190,11 @@ You can create a customer either through the Medusa admin or Admin REST APIs.
## Create B2B Price List
A price list allows you to set different prices on a set of products for different conditions. You can use this when building a B2B store to assign different prices for B2B customer groups.
A price list allows you to set different prices on a set of products for various conditions. When building a B2B store, you can use this to assign different prices for B2B customer groups.
You can use price lists to either set the same price for all B2B customers, or different prices for different B2B customers if you’ve created them in different customer groups.
You can use price lists to set the same price for all B2B customers or different prices for different B2B customers if you’ve organized them into separate customer groups.
You can create a price list either through the Medusa admin or Admin REST APIs. You can also import prices into your price list after creating it.
You can create a price list through the Medusa admin or Admin REST APIs. You can also import prices into your price list after creating it.
<DocCardList colSize={6} items={[
{
@@ -240,11 +237,11 @@ You can create a price list either through the Medusa admin or Admin REST APIs.
---
## Create Custom Entities
## Create Custom Entity
Your use case may be more elaborate than what is shown in this recipe. For example, you may need to have a Company entity that allows a business to register its employees as users with different privileges and configurations.
If you wish for a more advanced B2B sales flow, you can use Custom Entities to model Companies, Employees, Admins, and Buyers. This gives you more granular control of your B2B sales and allows you to build features like privileges, limits, and more.
Medusa can be customized to add custom entities, endpoints, services, and more. If you require some additional entities or a different logic in how you choose to implement a B2B store, you can customize Medusa as you see fit.
Each of the entities you create can be controlled using custom logic.
<DocCardList colSize={6} items={[
{
@@ -271,9 +268,9 @@ Medusa can be customized to add custom entities, endpoints, services, and more.
## Create an Endpoint to Check Customers
On the clients communicating with your store, such as the storefront, you’ll need to check if the currently logged-in customer is a normal customer or a B2B customer.
On the frontend clients communicating with your store, such as the storefront, you’ll need to check whether the currently logged-in customer is a B2B customer.
The endpoint’s logic is different based on how you’ve implemented the B2B logic. For example, if you’ve used the `is_b2b` flag in the customer group, your endpoint can check whether that flag is enabled for the logged-in customer.
The endpoint’s logic differs based on how you’ve implemented the B2B logic. For example, if you’ve used the `is_b2b` flag in the customer group, your endpoint can check whether that flag is enabled for the logged-in customer.
Medusa allows you to create custom endpoints exposed as REST APIs.
@@ -386,11 +383,11 @@ The Medusa admin plugin can be extended to add widgets, UI routes, and setting p
## Customize Storefront
On the storefront, you may want different login or registration interfaces for B2B and regular customers. You may also want to display products differently for each type of customer.
You may want different interfaces for B2B and regular customers on the storefront. You may also want to display products differently for each type of customer.
Medusa provides a Next.js starter that you can use and customize. You can also build your own storefront with any front-end technology. Medusa provides you with different client libraries and its REST APIs to use.
Medusa provides a Next.js starter that you can use and customize. You can also build your storefront with any frontend technology. Medusa provides you with different client libraries and REST APIs to use.
In the storefront, make sure to use the publishable API key you associated with your B2B sales channel to ensure only B2B products are retrieved.
Use the publishable API key you associated with your B2B sales channel in the storefront to ensure only B2B products are retrieved.
<DocCardList colSize={6} items={[
{

32
www/docs/content/recipes/commerce-automation.mdx
View File

@@ -12,9 +12,9 @@ This document guides you on how you can implement different forms of commerce au
## Overview
Commerce automation is essential for businesses that want to save costs, provide better user experience, and avoid manual, repetitive tasks that can lead to human errors. Businesses can utilize it in different domains, including marketing, customer support, order management, and more.
Commerce automation is essential for businesses that want to save costs, provide a better user experience, and avoid manual, repetitive tasks that can lead to human errors. Businesses can utilize it in different domains, including marketing, customer support, order management, and more.
Medusa provides you with the necessary architecture and resources to implement commerce automation related to order management, customer service, and more. Mainly, it utilizes an event bus that allows you to listen to certain event triggers and perform asynchronously actions.
Medusa provides the necessary architecture and resources to implement commerce automation related to order management, customer service, and more. It mainly utilizes an event bus that allows you to listen to specific event triggers and perform asynchronous actions.
This document gives a high-level overview of how you can implement different types of commerce automation.
@@ -69,11 +69,11 @@ Medusa already provides a [Re-stock notifications plugin](../plugins/other/resto
## 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. 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.
Using Medusa’s Notification Service, you can handle notifications triggered from actions on the customer’s orders or profile.
You can use Medusa's Notification Service to handle notifications triggered by actions on customer orders or profiles.
For example, when an order's status is updated, the `order.updated` event is triggered. You can create a Notification Service that handles this event by sending the customer an email informing them of the status update.
For example, when an order's status is updated, the `order.updated` event is triggered. You can create a Notification Service that handles this event by emailing the customer about the status update.
The [Event reference](../development/events/events-list.md) includes an extensive list of events triggered by the Medusa core.
@@ -184,7 +184,7 @@ export default NewNoteSubscriber
## Automatic Data Synchronization
As your commerce store gets bigger, you’ll likely need to synchronize data across different systems. For example, synchronizing data with an ERP system or a data warehouse.
As your commerce store grows, you'll likely need to synchronize data across different systems. For example, you can synchronize data with an ERP system or a data warehouse.
You can implement automatic synchronization in Medusa using scheduled jobs. A scheduled job runs at a specified date and time interval in the background of your Medusa backend. Within the scheduled job, you can synchronize your internal or external data.
@@ -272,11 +272,11 @@ Notice that here it’s assumed that:
## Order Management Automation
Using Medusa’s architecture and commerce features, you can automate a large amount of order management functionalities.
Using Medusa's architecture and commerce features, you can automate a large amount of order management functionalities.
By utilizing the event bus service, you can handle events within an order workflow to automate actions. For example, when an order is placed, you can listen to the `order.placed` event and automatically create a fulfillment if a set of predefined conditions are met.
Using the event bus service, you can handle events within an order workflow to automate actions. For example, when an order is placed, you can listen to the `order.placed` event and automatically creates a fulfillment if predefined conditions are met.
Another example is automatically capturing payment when an order is fully shipped and the `order.shipment_created` is triggered.
Another example is automatically capturing payment when an order is fully shipped, and the `order.shipment_created` is triggered.
<DocCardList colSize={4} items={[
{
@@ -312,15 +312,15 @@ Another example is automatically capturing payment when an order is fully shippe
## Automated RMA Flow
Business need to optimize their Return Merchandise Authorization (RMA) flow to ensure a good customer experience and service. By automating the flow, customers can request to return their received items, and businesses can quickly support them.
Businesses must optimize their Return Merchandise Authorization (RMA) flow to ensure a good customer experience and service. By automating the flow, customers can request to return their received items, and businesses can quickly support them.
Medusa’s commerce features are geared towards automating RMA flows and ensuring a good customer experience.
Medusa's commerce features are geared towards automating RMA flows and ensuring a good customer experience.
For example, customers can create returns for their orders without direct involvement from the store operator. The store operator will then receive a notification regarding the return and handle it accordingly. The same applies to order exchanges.
Medusa also allows the store operator to edit orders, receive customer approval for the edits, and authorize additional payment if necessary, all within a seamless workflow.
Similar to the examples mentioned earlier, each of these actions trigger events that you can listen to and perform additional actions based on your use case.
Similar to the examples mentioned earlier, each action triggers events you can listen to and perform additional actions based on your use case.
<DocCardList colSize={4} items={[
{
@@ -383,11 +383,11 @@ Similar to the examples mentioned earlier, each of these actions trigger events
## Customer Segmentation
Businesses use Customer Segmentation to oragnize customers into different groups, then apply different price rules to these groups. For example, you may group customers by their product preferences, the number of orders they’ve placed, or geographical location.
Businesses use Customer Segmentation to organize customers into different groups and then apply different price rules to these groups. For example, you may group customers by their product preferences, the number of orders they've placed, or geographical location.
Based on your use case and the logic of segmentation, you can use different Medusa automation development tools to detect a customer’s segment. Medusa also provides a Customer Groups feature that allows you to segment customers, whether you do it manually or automatically.
Based on your use case and the segmentation logic, you can use different Medusa automation development tools to detect a customer's segment. Medusa also provides a Customer Groups feature that allows you to segment customers, whether you do it manually or automatically.
For example, if you’re grouping together customers with more than twenty orders, you can use a Subscriber that listens to the `order.placed` event and checks the number of orders the customer has so far. Then, using Medusa’s Customer Groups feature, you can add that customer to the VIP group. Finally, you can utilize the Price Lists feature to provide different prices or discounts for customers in the VIP group.
For example, if you're grouping customers with over twenty orders, you can use a Subscriber that listens to the `order.placed` event and checks the number of orders the customer has so far. Then, you can add that customer to the VIP group using Medusa's Customer Groups feature. Finally, you can utilize the Price Lists feature to provide different prices or discounts for customers in the VIP group.
<DocCardList colSize={4} items={[
{
@@ -647,7 +647,7 @@ export default SendProductsNewsletterSubscriber
## Automation Development Toolkit
The use cases mentioned in this guide are just some examples of what commerce automation you can perform or implement with Medusa. Medusa provides the necessary development tools and mechanisms that allow you to automate tasks and manual work.
The use cases mentioned in this guide exemplify what commerce automation you can perform or implement with Medusa. Medusa provides the necessary development tools and mechanisms to automate tasks and manual work.
<DocCardList colSize={6} items={[
{

30
www/docs/content/recipes/digital-products.mdx
View File

@@ -12,13 +12,13 @@ This document guides you through the different documentation resources that will
## Overview
A business can sell digital or downloadable products. The products are stored privately using a storage service, such as S3, or other storage mechanism. When the customer buys this type of product, an email is sent to them where they can download the product.
Digital products are stored privately using a storage service like S3 or another storage mechanism. When the customer buys this type of product, an email is sent to them where they can download the product.
Medusa doesn't have a built-in concept of a digital product since our focus is standardizing features and implementations, then offering the building blocks that enable you to build your use-case easily.
Medusa doesn't have a built-in concept of a digital product since our focus is standardizing features and implementations, then offering the building blocks that enable you to build your use case.
You can create new entities that allow you to represent a digital product and link them to existing product-related entities.
You can create new entities to represent a digital product and link them to existing product-related entities.
Medusa’s plugins also allows you to choose the services that play part in your digital products implementation. Whether you want to use S3, MinIO, or another service to store your digital products, all you have to do is install an existing plugin or create your own. The same applies for sending notifications, such as emails, to the customer using notification services.
Medusa's plugins also allow you to choose the services that play a part in your digital product implementation. Whether you want to use S3, MinIO, or another service to store your digital products, you must install an existing plugin or create your own. The same applies to sending notifications, such as emails, to customers using notification services.
---
@@ -26,9 +26,9 @@ Medusa’s plugins also allows you to choose the services that play part in your
A file service is used to handle storage functionalities in Medusa. This includes uploading, retrieving, and downloading files, among other features. For digital products, a file service is essential to implement the basic functionalities of digital products.
The Medusa core defines an abstract file service that is extended by File Service plugins with the actual functionality. This allows you to choose the storage method that works best for your use case.
The Medusa core defines an abstract file service extended by File Service plugins with the actual functionality. This allows you to choose the best storage method for your use case.
By default, when you install a Medusa project, the Local file service plugin is installed. This plugin is useful for development, but it’s not recommended for production.
When you install a Medusa project, the Local file service plugin is installed by default. This plugin is helpful for development, but it's not recommended for production.
Medusa also provides official file service plugins that you can use in production, such as the [S3 plugin](../plugins/file-service/s3.mdx) or the [MinIO plugin](../plugins/file-service/minio.md). You can also create your own file service, or browse the [Plugins Library](https://medusajs.com/plugins/?filters=Storage&categories=Storage) for plugins created by the community.
@@ -68,9 +68,9 @@ Medusa also provides official file service plugins that you can use in productio
A notification service is used to handle sending notifications to users and customers. For example, when you want to send an order confirmation email or an email with reset-password instructions.
For digital products, a notification service allows you to send the customer an email, or another form of notification, with a link to download the file they purchased.
For digital products, a notification service allows you to send the customer an email or another form of notification with a link to download the file they purchased.
The Medusa core defines an abstract Notification service that is extended by Notification Service plugins with the actual functionality. This allows you to choose the notification method that best works for your use case.
The Medusa core defines an abstract Notification service extended by Notification Service plugins with the actual functionality. This allows you to choose the best notification method for your use case.
Medusa provides official notification plugins that you can use, such as the SendGrid plugin. You can also create your own notification service, or browse the [Plugins Library for plugins](https://medusajs.com/plugins/?filters=Storage&filters=Notification&categories=Storage&categories=Notification) created by the community.
@@ -110,9 +110,9 @@ Medusa provides official notification plugins that you can use, such as the Send
An entity represents a table in the database. The Medusa core defines entities necessary for the commerce features it provides. You can also extend those entities or create your own.
To represent a digital product, it’s recommended to create an entity that has a relation to the `ProductVariant` entity. The `ProductVariant` entity represents the saleable variant of a `Product`.
To represent a digital product, it's recommended to create an entity that has a relation to the `ProductVariant` entity. The `ProductVariant` entity represents the saleable variant of a `Product`.
For example, if you’re selling the Harry Potter movies, you would have a `Product` with the name “Harry Potter”, and for each movie in the series a `ProductVariant`. Each `ProductVariant` would be associated with the custom entity you create that represents the downloadable movie.
For example, if you're selling the Harry Potter movies, you would have a `Product` named “Harry Potter” and, for each movie in the series, a `ProductVariant`. Each `ProductVariant` would be associated with the custom entity you create that represents the downloadable movie.
<DocCardList colSize={6} items={[
{
@@ -230,7 +230,7 @@ npx medusa migrations run
## Add Custom Endpoints
After creating your entity, you need to create custom admin endpoints that allows you to access and manipulate that entity. The endpoints necessary vary based on your case, but generally speaking you’ll need endpoints to perform Create, Read, Update, and Delete (CRUD) functionalities.
After creating your entity, you need to create custom admin endpoints that allow you to access and manipulate that entity. The endpoints necessary vary based on your case, but generally speaking, you'll need endpoints to perform Create, Read, Update, and Delete (CRUD) functionalities.
:::tip
@@ -238,7 +238,7 @@ The Medusa backend provides the necessary endpoints for the actual file upload.
:::
You can also create custom storefront endpoints that allows you to show information related to the downloadable digital product if this information isn’t stored within the `Product` or `ProductVariant` entities.
You can also create custom storefront endpoints that allow you to show information related to the downloadable digital product if this information isn't stored within the `Product` or `ProductVariant` entities.
Creating an endpoint also requires creating a service, which is a class that typically holds utility methods for an entity. You can implement the CRUD functionalities as methods within the service, then access the service in an endpoint and use its methods.
@@ -564,9 +564,9 @@ export default (rootDirectory: string): Router | Router[] => {
## Customize Admin Dashboard
The Medusa admin dashboard provides merchants with an easy-to-use interface to manage their store’s data and settings. It’s also extendable to add widgets, pages, and setting pages relevant to your use case.
The Medusa admin dashboard provides merchants with an easy-to-use interface to manage their store's data and settings. It's also extendable, so you can add widgets, pages, and setting pages relevant to your use case.
To add an interface that allows the admin user to upload digital products, you can create custom widgets or pages that uses the routes you created. For the actual file upload, you can use the [Protected Files Upload endpoint](https://docs.medusajs.com/api/admin#uploads_postuploadsprotected).
To add an interface that allows the admin user to upload digital products, you can create custom widgets or pages that use the routes you created. You can use the [Protected Files Upload endpoint](https://docs.medusajs.com/api/admin#uploads_postuploadsprotected).
<DocCardList colSize={4} items={[
{
@@ -959,7 +959,7 @@ If you open the admin now, you’ll find a new Digital Products item in the side
When a customer purchases a digital product, they should receive a link to download it.
To implement that, you first need to listen to the `order.placed` event using a Subscriber. Then, in the handler method of the subscriber, you check for the digital products in the order, and obtain the download URLs using the file service’s `getPresignedDownloadUrl` method.
To implement that, you first need to listen to the `order.placed` event using a Subscriber. Then, in the handler method of the subscriber, you check for the digital products in the order and obtain the download URLs using the file service's `getPresignedDownloadUrl` method.
Finally, you can send a notification, such as an email, to the customer using the Notification Service of your choice. That notification would hold the download links to the products they purchased.

82
www/docs/content/recipes/multi-region.mdx
View File

@@ -7,31 +7,31 @@ import Icons from '@theme/Icon';
# Multi-Regional Store
This document guides you through the different features and resources available in Medusa to create a multi-regional store.
This document guides you through Medusa's different features and resources to create a multi-regional store.
## Overview
A multi-regional store allows merchants to sell across different countries. This includes supporting each country’s tax rules, currency, available shipping and payment options, and more.
A multi-regional store allows merchants to sell across different countries. This includes supporting each country's tax rules, currency, available shipping and payment options, and more.
Medusa provides the necessary features to create a multi-regional store out of the box. This recipe explains how you can benefit from Medusa’s features to create a multi-regional store.
Medusa comes with multi-regional support out of the box. This recipe explains how you can benefit from Medusa's features to create a multi-regional store.
---
## Multi-Region Setup
With Medusa, you can create an unlimited number of regions in your store. Each region can have its own configurations. These configurations can be managed either through the Medusa admin or the Admin REST APIs.
With Medusa, you can create unlimited regions in your store. Each region has configurations managed through the Medusa Admin Dashboard or the Admin API.
### Currency
Merchants can specify the currency of each region. Multiple regions can have the same currency, but a region can have only one currency.
This affects what currency are prices shown to the customer in a region. As explained later, this also affects what prices are shown to the customer as well in a region.
When customers view your products from a region, they see the prices in the region’s currency. As explained later, this also affects which prices are shown to the customer in a region.
### Tax rates and providers
Merchants can define for each region a default tax rate and tax rates for specific conditions (for example, for a specific set of products). Each region can also have a different tax provider that calculates the taxes. You can use Medusa’s default tax provider, or create your own tax provider.
At the regional level, merchants can define a default tax rate and tax rates for specific conditions (for example, for a particular set of products). Each region can also have a different tax provider that calculates the taxes. You can use Medusa's default tax provider or create a custom tax provider.
During checkout, the taxes are calculated based on the customer’s region and its taxes configurations and rates.
During checkout, the taxes are calculated based on the customer's region, tax configurations, and rates.
<DocCardList colSize={4} items={[
{
@@ -65,11 +65,11 @@ During checkout, the taxes are calculated based on the customer’s region and i
### Payment and Fulfillment Providers
Merchants can choose which payment and fulfillment providers are available in which regions. For example, a region may have Stripe enabled as a payment provider, while another may have PayPal enabled instead.
Merchants can choose which payment and fulfillment providers are available in each region. For example, one region can use Payment Provider A and B while another only uses Payment Provider B.
This affects what payment and shipping methods are shown to the customer during checkout. Customers can only use the methods enabled in their region.
Customers will only be shown the payment providers and shipping options configured for the region during checkout. This lets you give customers a localized experience that feels familiar and instills trust.
Medusa provides official plugins for payment and fulfillment providers. You can also create your own providers.
Medusa provides official plugins for payment and fulfillment providers. You can also create custom providers.
<DocCardList colSize={6} items={[
{
@@ -114,11 +114,11 @@ Medusa provides official plugins for payment and fulfillment providers. You can
## Prices Per Region and Currency
When a merchant sets the price of a product in Medusa, they can specify the price per currency and per region. Merchants can also benefit from this pricing mechanism when adding sales or overriding prices for specific conditions using the [Price Lists feature](../modules/price-lists/overview.mdx).
When a merchant sets the price of a product in Medusa, they can specify the price per currency and region. Merchants can also benefit from this pricing mechanism when adding sales or overriding prices for specific conditions using the [Price Lists feature](../modules/price-lists/overview.mdx).
Then, customers see the price of a product based on the region they’re in and the region’s currency, and whether any special pricing applies to their case. Medusa has a pricing strategy (which you can override) to show the customer the best price based on their context.
Then, customers see the price of a product based on the region they're in and the region's currency and whether any special pricing applies to their case. Medusa has a pricing strategy (which you can override) to show the customer the best price based on their context.
Using the [tax-inclusive beta feature](../beta.md#tax-inclusive-pricing), merchants can also specify prices that include taxes per currency and region. Medusa then takes care of calculating the tax amount applied to a line item in the cart based on the region’s tax configurations.
Using the [tax-inclusive beta feature](../beta.md#tax-inclusive-pricing), merchants can 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.
<DocCardList colSize={6} items={[
{
@@ -143,55 +143,11 @@ Using the [tax-inclusive beta feature](../beta.md#tax-inclusive-pricing), mercha
---
## Product Availability Per Region
In a multi-regional setup, you may have products that should only be available in certain regions. Using the Sales Channels feature, you can control the availability of products within different channels.
Sales channels aren’t directly associated with regions by default, but you can create a custom relation between the `SalesChannel` entity and the `Region` entity. Alternatively, you can utilize the `metadata` attribute of each entity, which is an attribute that can be used to add custom data, to set the ID of the associated sales channel or region for each entity.
Then, when a customer is viewing the products from a region, only the products available in the region’s associated sales channel are retrieved and shown to the customer.
This also allows you to create or deploy different storefronts for different regions, if necessary. Each storefront only shows the products available in a region and its sales channel.
It should also be noted that a cart is associated with a region and a sales channel. So, customers can only buy a product if it belongs to the same sales channel as the cart.
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/modules/sales-channels/overview',
label: 'Sales Channels Overview',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn about the sales channel feature in Medusa.',
}
},
{
type: 'link',
href: '/development/entities/extend-entity',
label: 'Extend Entities',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to extend entities in the Medusa backend.',
}
},
{
type: 'link',
href: '/modules/sales-channels/storefront/use-sales-channels',
label: 'Show Products by Sales Channel',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to show products by a sales channel in the storefront.',
}
},
]} />
---
## Multi-Warehouse Support
Medusa provides Multi-warehouse features that allow you to manage your inventory across different locations. Merchants can then control which location an item in an order is fulfilled from, allowing them to keep a correct inventory count across locations and selling channels.
Medusa provides Multi-warehouse features that allow you to manage your inventory across different locations. Merchants can then control which location an item in an order is fulfilled, allowing them to keep a correct inventory count across locations and sales channels.
In a multi-regional setup, this can allow you to manage your inventory through Medusa across the different regions you serve. Your products’ inventory and availability aren’t bound to a single stock location, and customers are always shown accurate inventory information based on the location associated with their sales channel.
A multi-regional setup lets you manage your inventory through Medusa across the different regions you serve. Your products’ inventory and availability aren't bound to a single stock location, and customers are always shown accurate inventory information based on the location associated with their sales channel.
<DocCardList colSize={4} items={[
{
@@ -227,9 +183,9 @@ In a multi-regional setup, this can allow you to manage your inventory through M
## Multi-Lingual Setup with Third-Party CMS
Medusa can be integrated with any third-party services, including Content Management Systems (CMS). With a third-party CMS, you can benefit from rich CMS features, including managing your content in multiple languages. This allows you to cater to customers’ different languages in the regions you serve.
Medusa can be integrated with third-party services, including Content Management Systems (CMS). You can benefit from rich CMS features with a third-party CMS, including managing your content in multiple languages. This allows you to cater to customers’ different languages in the regions you serve.
Medusa provides an official Contentful plugin and a community Strapi plugin. You can also create your own CMS plugin that integrates with your preferred CMS platform to provide multi-lingual features.
Medusa provides an official Contentful plugin and a community Strapi plugin. You can also create a CMS plugin that integrates with your preferred CMS platform to provide multi-lingual features.
<DocCardList colSize={6} items={[
{
@@ -256,9 +212,9 @@ Medusa provides an official Contentful plugin and a community Strapi plugin. You
## Automatic Location Detection
When you sell across regions, it’s important to be able to detect the customer’s region and provide them with the products, prices, and content relevant to them without requiring actions from their side.
When you sell across regions, it's essential to be able to detect the customer's region and provide them with the products, prices, and content relevant to them without requiring actions from their side.
Medusa provides an IP Lookup plugin that allows you to detect a customer’s location and, ultimately, their region using [ipstack](https://ipstack.com/). You can also create a plugin that detects the location through a different logic.
Medusa provides an IP Lookup plugin that lets you detect a customer's location and, ultimately, their region using [ipstack](https://ipstack.com/). You can also create a plugin that detects the location through a different logic.
<DocCardList colSize={6} items={[
{

37
www/docs/content/recipes/omnichannel.mdx
View File

@@ -5,23 +5,25 @@ addHowToData: true
import DocCardList from '@theme/DocCardList';
import Icons from '@theme/Icon';
# Omnichannel Store
# Omnichannel Commerce
This document guides you through the different documentation resources that will help you build an omnichannel store with Medusa.
This document guides you through the different documentation resources that will help you build omnichannel commerce with Medusa.
## Overview
An omnichannel store provides customers with a seamless shopping experience, no matter where they’re shopping from. Whether they’re buying your products from your online store, a marketplace like Amazon, or through social media, you should provide them with a good experience and handle orders consistently.
Merchants selling across different channels need an efficient way to manage their commerce data and operations across these channels. Omnichannel commerce solves this problem by allowing merchants to support multiple channels through a single system while maintaining layers of separation.
Medusa’s headless backend facilitates building an omnichannel store, as your backend and storefront aren’t tightly coupled. You can also utilize plugins and Medusa’s sales channels feature to expand your business into other avenues like marketplaces and social commerce.
Omnichannel commerce also provides customers a seamless shopping experience, regardless of where they’re shopping. Whether they’re buying your products from your online store, a marketplace like Amazon, or through social media, you should provide them with a good experience and handle orders consistently.
Medusa’s headless backend facilitates building omnichannel commerce, as your backend and storefront aren’t tightly coupled. You can also utilize plugins and Medusa’s sales channels feature to expand your business into other avenues like marketplaces and social commerce.
---
## Create Multiple Storefronts with One Backend
When creating an omnichannel commerce store, you’ll likely build multiple webshops or mobile apps. All these storefronts should be able to provide your customers with a similar experience and allow them to browse products and place orders.
You’ll likely build multiple webshops or mobile apps when creating omnichannel commerce. All these storefronts should be able to provide your customers with a similar experience and allow them to browse products and place orders.
Medusa’s headless backend allows all storefronts to interact with Store REST APIs to provide the same commerce functionalities. This separation also gives you the freedom to choose your tech stack for the different storefronts you’re creating.
Medusa’s headless backend allows all storefronts to interact with Store REST APIs to provide the same commerce functionalities. This separation also allows you to choose your tech stack for the different storefronts you’re creating.
<DocCardList colSize={6} items={[
{
@@ -48,11 +50,11 @@ Medusa’s headless backend allows all storefronts to interact with Store REST A
## Integrate with Marketplaces and Social Commerce
Businesses are no longer bound to sell in their own stores. They can reach their customers through their different shopping channels.
Businesses are no longer bound to sell in their stores. They can reach their customers through their different shopping channels.
One example is marketplaces like Amazon. Customers searching through Amazon to find products are inadvertently searching through a huge number of third-party stores connected to Amazon’s marketplace.
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.
With Medusa, you can use the Sales Channels feature that allows you to set different product availability across sales channels. You can then integrate with Amazon’s seller program and use their APIs to push your products on Amazon. This integration can be achieved through a custom plugin that you create and install on your Medusa backend.
With Medusa, you can use the Sales Channels feature to set different product availability across sales channels. You can then integrate with Amazon’s seller program and use their APIs to push your products on Amazon. This integration can be achieved through a custom plugin you create and install on your Medusa backend.
Another channel that attracts customer sales is social media. Customers browsing a social media app can now find products and buy them. With an approach similar to what was mentioned above, you can create a plugin in your Medusa backend that integrates with social media apps to show your products and sell them to customers on the app.
@@ -81,15 +83,15 @@ Another channel that attracts customer sales is social media. Customers browsing
## Optimize Customer Experience
Each business has a unique brand and wants to provide customers with the best journey and experience. With Medusa’s modular architecture, businesses can focus on bringing their brands to life without any restrictions.
With Medusa’s modular architecture, businesses can focus on bringing their brands to life without restrictions.
For your storefronts, you can implement the customer journey and design that leads to the best customer experience. The backend does not impose any restrictions on how the frontend is built.
You can implement the customer journey and design for your storefronts that leads to the best customer experience. The backend does not impose any restrictions on how the frontend is built.
Medusa’s architecture also makes it easier to integrate any third-party services necessary to provide a better customer experience with a plugin. This plugin’s functionality can be accessible to the storefronts connected to the Medusa backend.
For example, if you’ve integrated a search plugin such as Algolia in the Medusa backend, the storefronts can utilize it through the Search Products endpoint. Another example is installing the Stripe payment plugin on the backend, and utilizing it in your storefronts to make payments before placing an order.
For example, if you’ve integrated a search plugin like Algolia in the Medusa backend, the storefronts can utilize it through the Search Products endpoint. Another example is installing the Stripe payment plugin on the backend and using it in your storefronts to make payments before placing an order.
<DocCardList colSize={4} items={[
<DocCardList colSize={6} items={[
{
type: 'link',
href: '/development/plugins/create',
@@ -99,15 +101,6 @@ For example, if you’ve integrated a search plugin such as Algolia in the Medus
description: 'Learn how to create a plugin.',
}
},
{
type: 'link',
href: '/plugins/overview',
label: 'Official Plugins',
customProps: {
icon: Icons['bolt-solid'],
description: 'Check out available official plugins.',
}
},
{
type: 'link',
href: 'https://medusajs.com/plugins/',

133
www/docs/content/recipes/oms.mdx
View File

@@ -7,13 +7,13 @@ import Icons from '@theme/Icon';
# Order Management System (OMS)
This document guides you through the different features and resources available in Medusa to use it as an order management system (OMS).
This document guides you through Medusa's different features and resources to use it as an order management system (OMS).
## Overview
An order management system (OMS) is a system that provides features to track and manage orders and typically integrates with third-party services to handle payment, fulfillment, and more. Businesses use an OMS as part of a bigger commerce ecosystem that uses different services to achieve the business use case.
When you build or integrate an OMS, you face certain challenges, such as accepting orders from different sales channels, tracking inventory across the sales channels, and integrating third-party fulfillment and payment providers with the OMS.
Medusa can be used within a larger ecosystem as an OMS. Its modular architecture and commerce features make it easy for developers to integrate it with other services while utilizing powerful OMS features, including returns, exchanges, and order edits.
Medusa provides the building blocks that allow you to integrate it as an OMS within a larger commerce ecosystem. Its commerce features and modular architecture 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.
:::tip
@@ -25,15 +25,17 @@ Recommended read: [How Siam Makro used Medusa an OMS](https://medusajs.com/blog/
## Source Orders into Medusa
Since an OMS is part of a larger ecosystem, your orders will likely come from different sources or channels. All these channels must ultimately direct their order to the OMS. This can be done in different ways in Medusa depending on your use case.
Orders from different sales channels in your commerce ecosystem must all route their orders into the OMS.
The basic way would be to use the REST APIs to create an order in Medusa. You can use the [Store REST APIs](https://docs.medusajs.com/api/store#carts), which are useful if the order is placed directly by the customer such as through a storefront. Alternatively, you can use the [Draft Orders](https://docs.medusajs.com/api/admin#draft-orders) feature that allows you to create the order without customer interference. This method can be helpful if you’re creating the order through an automated script or from a channel managed by a store operator, such as a [POS](./pos.mdx).
![Routing orders into Medusa OMS](https://res.cloudinary.com/dza7lstvk/image/upload/v1695115403/Medusa%20Docs/Diagrams/oms-orders_to4yaq.jpg)
If your use case is more advanced or complex, you can create a custom endpoint that gives you more control over how you create the order. For example, you can create a custom endpoint that allows creating or inserting a batch of orders.
Medusa's [Store REST APIs](https://docs.medusajs.com/api/store) let you integrate a checkout experience in any storefront. Alternatively, you can use Medusa's [Draft Order APIs](https://docs.medusajs.com/api/admin#draft-orders) to place an order without direct involvement from the customer, such as when placing an order through a POS.
You can also create a Scheduled Job to import orders into Medusa from an external service or system at a defined interval.
You can implement customizations in your backend if you accept orders through a third-party checkout system and need more flexibility over adding orders to Medusa.
<DocCardList colSize={6} items={[
You can add support for importing orders into Medusa through a custom endpoint that allows batch-inserting orders. Alternatively, you can create a scheduled job that runs at a specified interval and imports orders from an external service.
<DocCardList colSize={4} items={[
{
type: 'link',
href: 'https://docs.medusajs.com/api/store#carts',
@@ -43,15 +45,6 @@ You can also create a Scheduled Job to import orders into Medusa from an externa
description: 'Learn how to use the Store REST APIs to create an order.',
}
},
{
type: 'link',
href: 'https://docs.medusajs.com/api/admin#draft-orders',
label: 'Draft Order APIs',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn about available Draft Order Admin REST APIs.',
}
},
{
type: 'link',
href: '/development/endpoints/create',
@@ -76,13 +69,13 @@ You can also create a Scheduled Job to import orders into Medusa from an externa
## Route Orders to Third-party Fulfillment Services
In your ecosystem, you have different third-party services and tools that handle the fulfillment of orders. The OMS integrates with these services to ensure they’re used when fulfillment events occur.
You can integrate third-party fulfillment providers with Medusa by creating a fulfillment service class or using a fulfillment plugin.
With Medusa, you can integrate third-party fulfillment services either by creating a fulfillment provider or installing an existing fulfillment plugin. The fulfillment provider must implement different methods that are used when fulfillment actions are taken on the order.
Medusa uses the fulfillment service whenever a fulfillment action is performed, such as when a fulfillment is created for items in an order. The service's methods interact with the third-party provider to handle the desired fulfillment actions.
For example, when an admin creates a fulfillment on an order, the method defined in the fulfillment provider associated with the order is executed. In that method, you can create the necessary implementation that handles creating the fulfillment in the third-party service.
![Fulfilling orders with Medusa OMS](https://res.cloudinary.com/dza7lstvk/image/upload/v1695115456/Medusa%20Docs/Diagrams/oms-fulfillment_kfi1iz.jpg)
In addition, Medusa has an event bus that allows you to listen to events and perform an action asynchronously when that event is triggered. So, you can listen to fulfillment-related events, such as the `order.fulfillment_created` event, and handle that event in the subscribed method when it’s triggered.
In addition, Medusa has an event bus that allows you to listen to events and perform a task asynchronously when that event is triggered. So, you can listen to fulfillment-related events, such as the `order.fulfillment_created` event, and handle that event in the subscribed handler method.
<DocCardList colSize={6} items={[
{
@@ -109,11 +102,9 @@ In addition, Medusa has an event bus that allows you to listen to events and per
## Process Payment with Third-Party Providers
Similar to fulfillment services, you’ll also have payment providers that handle processing payments. Your OMS integrates with these providers to handle payment-related actions.
Like fulfillment services, you can integrate third-party payment providers with Medusa by creating a payment processor or using payment plugins.
Medusa allows you to integrate third-party payment providers by creating a payment processor. The payment processor must implement different methods that are used when the order’s payment is being processed, such as when it’s captured or refunded.
Alternatively, you can use existing payment plugins. Medusa provides official payment plugins for [Stripe](../plugins/payment/stripe.mdx), [PayPal](../plugins/payment/paypal.md), and [Klarna](../plugins/payment/klarna.md).
When a payment action occurs, such as capturing payment, Medusa uses the integrated payment provider to perform these actions. Medusa also emits payment-related events, such as `order.payment_captured`, that can be handled by a subscriber.
<DocCardList colSize={6} items={[
{
@@ -138,17 +129,51 @@ Alternatively, you can use existing payment plugins. Medusa provides official pa
---
## Track Inventory Across Sales Channels
Medusa's multi-warehouse and sales channel features 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.
In addition, Medusa's inventory and stock location modules that power its multi-warehouse features can be replaced entirely with a custom implementation. You can then take control of how inventory functionalities are implemented in Medusa.
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/modules/multiwarehouse/overview',
label: 'Multi-warehouse',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn about the Multi-warehouse architecture and features.',
}
},
{
type: 'link',
href: '/modules/sales-channels/overview',
label: 'Sales Channels',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn about the Sales Channel architecture and features.',
}
},
{
type: 'link',
href: '/development/plugins/create',
label: 'Create a Plugin',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create a plugin that can be installed in a Medusa backend.',
}
},
]} />
---
## Handle Returns, Exchanges, and Edits
Medusa provides advanced order features that make it an ideal OMS choice and allow you to provide a great customer experience.
In Medusa, items in an order can be returned or exchanged; they can be created by the merchant or requested by the customer. A merchant can also edit an order to add, update, or delete items.
Items in an order can be returned or exchanged. The return or exchange can either be requested by the customer or created by an admin. Once created, they reflect changes in the order’s total and inventory and allow the admin to issue a refund to the customer as well if necessary. In the case of exchanges, the fulfillment provider will be used to fulfill the new item sent to the customer.
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 providers are used if fulfillment or payment actions are required, such as fulfilling exchanged items.
Orders can also be edited to add, update, or delete items in an order. Additional payment can be authorized, or a refund can be issued, if necessary. Once an order edit is confirmed, the changes are reflected on the order’s totals and inventory.
These features can be used through the [Admin](https://docs.medusajs.com/api/admin) and [Store REST APIs](https://docs.medusajs.com/api/store). You can also perform these actions in your custom endpoints or services using the [core services](../references/services/index.md) and their methods.
Once these actions occur, events, such as `order.return_requested` are triggered by Medusa’s event bus. So, you can listen to different events to perform asynchronous actions, for example, to communicate with third-party services or tools.
Medusa also emits events related to these actions, such as `order.return_requested`. So, you can listen to these events and perform asynchronous actions, such as communicating with third-party services.
<DocCardList colSize={6} items={[
{
@@ -191,50 +216,6 @@ Once these actions occur, events, such as `order.return_requested` are triggered
---
## Track Inventory Across Sales Channels
An OMS typically connects to more than one sales channel, such as one or more storefronts and a POS. It’s important to keep track of your inventory across these sales channels.
Medusa’s multi-warehouse and sales channel features allow you to track inventory levels across different stock locations, which are tied to sales channels. When an order is placed, an item in a stock location, based on the order’s sales channel, is reserved. Once the item is fulfilled, the reserved quantity is deducted from the item’s inventory quantity.
The inventory is also changed when an item is returned, exchanged, or when an order is edited.
Medusa’s inventory and stock location modules that power its multi-warehouse features can also be completely replaced with a custom implementation. This allows you to take control of how inventory functionalities are implemented in Medusa.
In addition, you can integrate third-party inventory systems by creating or installing a plugin. Medusa provides an official [Brightpearl](https://github.com/medusajs/medusa/tree/develop/packages/medusa-plugin-brightpearl) plugin that syncs orders and inventory with Brightpearl.
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/modules/multiwarehouse/overview',
label: 'Multi-warehouse',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn about the Multi-warehouse architecture and features.',
}
},
{
type: 'link',
href: '/modules/sales-channels/overview',
label: 'Sales Channels',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn about the Sales Channel architecture and features.',
}
},
{
type: 'link',
href: '/development/plugins/create',
label: 'Create a Plugin',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create a plugin that can be installed in a Medusa backend.',
}
},
]} />
---
## Additional Development and Commerce Features
Medusa provides more commerce features that you can learn about in the [Commerce Modules](../modules/overview.mdx) section of this documentation.

52
www/docs/content/recipes/personalized-products.mdx
View File

@@ -7,11 +7,11 @@ import Icons from '@theme/Icon';
# Personalized Products
This document guides you through the different documentation resources that will help you build personalized products with Medusa.
This document guides you through the different documentation resources to help you build personalized products with Medusa.
## Overview
Commerce stores that provide personalized products allow customers to pick and choose how the product looks or what features it includes. For example, they can upload an image to print on a shirt or provide a message to include in a letter.
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.
Medusa’s customizable architecture allows you to customize its entities or create your own to implement and store personalized products. Also, as the Medusa backend is headless, you have freedom in how you choose to implement the storefront. This is essential for ecommerce stores that provide personalized products, as you typically build a unique experience around your products.
@@ -19,7 +19,7 @@ Medusa’s customizable architecture allows you to customize its entities or cre
## Store Personalized Data
Most of the entities in Medusa’s core include a `metadata` attribute. This attribute is helpful for storing custom data in the core entities.
Most of the entities in Medusa’s core include a `metadata` attribute. This attribute helps store custom data in the core entities.
The `Product` entity represents the main product, whereas the `ProductVariant` is the different saleable options of that product. For example, a shirt is a `Product`, and each different color of the shirt is the `ProductVariant`. The `LineItem` entity is the product variant added to the cart.
@@ -27,6 +27,8 @@ So, you can use the `metadata` attribute of the `LineItem` entity to store the c
For example, if you’re asking customers to enter a message to put in a letter they’re purchasing, you can use the `metadata` attribute of the `LineItem` entity to set the personalized information entered by the customer.
Note that two Line Items in the cart having different `metadata` attributes are not considered the same item. So, each Line Item is managed separately and can have its own quantity.
In more complex cases, you can extend entities from the core, such as the `Product` entity, to add more attributes. You can also create new custom entities to hold your personalized data and logic.
<DocCardList colSize={4} items={[
@@ -63,7 +65,7 @@ In more complex cases, you can extend entities from the core, such as the `Produ
## Build a Custom Storefront
Medusa provides a headless backend that can be accessed through REST APIs. So, there are no restrictions in what language or framework you use to build the storefront, or what design or experience you provide to customers.
Medusa provides a headless backend that can be accessed through REST APIs. So, there are no restrictions on what language or framework you use to build the storefront or what design or experience you provide customers.
You can build a unique experience around your products that focuses on the customer’s personalization capabilities.
@@ -94,7 +96,7 @@ Medusa provides a Next.js storefront starter with basic ecommerce functionalitie
## Pass Personalized Data to the Order
If you followed the basic approach of using the `metadata` attribute to store the personalized data, you can pass the personalization data when you add an item to the cart in the storefront using the [Add a Line Item](https://docs.medusajs.com/api/store#carts_postcartscartlineitems) endpoint. This endpoint accepts a `metadata` request body parameter that will be stored in the created line item’s `metadata` attribute.
If you followed the basic approach of using the `metadata` attribute to store the personalized data, you can pass the personalization data when you add an item to the cart in the storefront using the [Add a Line Item](https://docs.medusajs.com/api/store#carts_postcartscartlineitems) endpoint. This endpoint accepts a `metadata` request body parameter that will be stored in the created Line Item’s `metadata` attribute.
In the case that you’ve created a custom entity or extended a core entity, you can create a custom endpoint that handles saving the personalization data. You can then call that endpoint from the storefront before or after adding the item to the cart.
@@ -123,11 +125,11 @@ In the case that you’ve created a custom entity or extended a core entity, you
## Access Personalized Data in the Order
If you stored the personalized data in the `metadata` of the line items, those same line items are associated with the placed order. So, by expanding the `items` relation on the `Order` entity, you can retrieve the `metadata` attribute of the line items.
If you stored the personalized data in the `metadata` of the Line Items, those same Line Items are associated with the placed order. So, by expanding the `items` relation on the `Order` entity, you can retrieve the `metadata` attribute of the Line Items.
In the case that you’ve created a custom entity or extended a core entity, you can create a custom endpoint that handles retrieving the personalization data. If the entity you’ve created or customized is associated with the Order entity, you can alternatively expand it similarly to the `items` relation.
If you want to show the personalized data in the Medusa admin, you can extend the Medusa admin to add a widget, a UI route, or a setting page, and show the personalized data.
If you want to show the personalized data in the Medusa admin, you can extend the Medusa admin to add a widget, a UI route, or a setting page and show the personalized data.
<DocCardList colSize={4} items={[
{
@@ -161,6 +163,42 @@ If you want to show the personalized data in the Medusa admin, you can extend th
---
## Fulfill Personalized Products in Orders
Once a customer places an order, the `order.placed` event is emitted in the backend. You can listen to this event with a Subscriber to access the order’s details and fulfill its personalized products.
For example, if the customer personalizes a shirt to include an image or message, you can listen to the `order.placed` event to send their request to the printing fulfillment machine or service.
You can also listen to other [Order-related events](../development/events/events-list.md#order-events) to perform this action at a different point if necessary, such as when the `order.fulfillment_created` is triggered.
Alternatively, you can create a fulfillment service that integrates a third-party service or mechanism to fulfill the personalized product. This is useful if you want the fulfillment of personalized products to be embedded into Medusa’s existing order fulfillment.
- Create a Subscriber
- Create a Fulfillment Service
<DocCardList colSize={6} items={[
{
type: 'link',
href: '/development/events/create-subscriber',
label: 'Create a Subscriber',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create a subscriber and listen to events.',
}
},
{
type: 'link',
href: '/modules/carts-and-checkout/backend/add-fulfillment-provider',
label: 'Create a Fulfillment Service',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create a fulfillment provider in Medusa.',
}
},
]} />
---
## Additional Development
You can find other resources for your personalized products development in the [Medusa Development section](../development/overview.mdx) of this documentation.

50
www/docs/content/recipes/pos.mdx
View File

@@ -7,15 +7,13 @@ import Icons from '@theme/Icon';
# POS
This document guides you through the different features and resources available in Medusa to create a point-of-sale (POS) system.
This document guides you through Medusa's different features and resources to create a point-of-sale (POS) system.
## Overview
A POS system can be used in a business’s retail or offline stores to access and manage products and their inventories, and place orders for customers. Based on your use case, you can provide more features that can improve the customer experience. For example, customer discounts or Return Merchandise Authorization (RMA) features.
Building a POS system on top of an ecommerce engine introduces challenges related to the tech stack used, data sync across channels, and feature availability relevant to offline sales in a POS, not just online sales.
Medusa’s architecture, commerce features, and customization capabilities allow you to build a POS system without any limitations or restrictions.
Medusa’s headless backend facilitates creating any type of frontend that can communicate with the backend, including a POS system. Also, Medusa’s commerce features, including mutli-warehouse, sales channels, and order management features, can power your POS system to provide essential features for both store operators and customers making their purchase.
Medusa's modular architecture solves these challenges. Any frontend can utilize Medusa's commerce features through its REST APIs. Medusa's commerce features include multi-warehouse and sales channel features that facilitate integrating a POS system.
:::tip
@@ -27,11 +25,11 @@ Recommended read: [How Tekla built a POS system with Medusa](https://medusajs.co
## Freedom in Choosing Your POS Tech Stack
When you decide to build a POS system, you have to make an important choice of which programming framework, language, or tool you want to use. In most cases, this can be interdependent on the commerce engine, as it can limit your choices.
When you build a POS system, you must choose which programming framework, language, or tool you want to use.
Medusa’s modular architecture removes any restrictions you may have while making this choice. Regardless of what you choose, any client or front end can connect to the Medusa backend using its headless REST APIs. So, when building the POS system, you’ll be interacting with the [Admin REST APIs](https://docs.medusajs.com/api/admin).
Medusa's modular architecture removes any restrictions you may have while making this choice. Any client or front end can connect to the Medusa backend using its headless REST APIs.
For example, you can use [Expo](https://expo.dev/) with [React Native](https://reactnative.dev/) to build a cross-platform POS app. In this case, you can also utilize [Medusa’s JavaScript client](../js-client/overview.md) to make it even easier to send requests to the backend.
![POS Tech Stack](https://res.cloudinary.com/dza7lstvk/image/upload/v1695114981/Medusa%20Docs/Diagrams/pos-tech-stack_j6mkyc.jpg)
<DocCardList colSize={4} items={[
{
@@ -67,13 +65,13 @@ For example, you can use [Expo](https://expo.dev/) with [React Native](https://r
## Integrate a Barcode Scanner
An essential feature a POS system needs is the capability to search and find products by scanning their barcode. You can then check their inventory information or add them to the customer’s order.
POS systems make the checkout process smoother by integrating a barcode scanner. Merchants can scan a product by its barcode to check its details or add it to the customer's purchase.
Medusa’s [Product Variant entity](../references/entities/classes/ProductVariant.md), which represents a saleable stock item, already includes the necessary attributes to implement this integration, mainly the `barcode` attribute. Other notable attributes include `ean`, `upc`, and `hs_code`, among others.
Medusa’s [Product Variant entity](../references/entities/classes/ProductVariant.md) includes the necessary attributes to implement this integration, mainly the `barcode` attribute. Other notable attributes include `ean`, `upc`, and `hs_code`, among others.
To search through product variants by their barcode, you can create a custom endpoint and use it within your POS. The endpoint can receive the item’s barcode, and return all product variants having that barcode.
To search through product variants by their barcode, you can create a custom endpoint and call it within your POS.
You can also create another custom endpoint that allows you to scan products in your store by their barcode and automatically add them to your backend. This eliminates the need to enter your product details manually.
![Example flow of integrating a barcode scanner](https://res.cloudinary.com/dza7lstvk/image/upload/v1695115066/Medusa%20Docs/Diagrams/pos-scan-barcode_xaa61c.jpg)
<DocCardList colSize={6} items={[
{
@@ -133,7 +131,7 @@ export default (rootDirectory: string): Router | Router[] => {
const router = Router()
router.get(
"/store/search-barcode",
"/pos/search-barcode",
cors(storeCorsOptions),
wrapHandler(
async (req: Request, res: Response) => {
@@ -174,15 +172,13 @@ export default (rootDirectory: string): Router | Router[] => {
## Access Accurate Inventory Details
As you manage an online and offline store, it’s important to make a separation between inventory quantity across different locations. For example, when an online order is made, the change in the inventory quantity of the order items should be made from the warehouse’s inventory, and not from the retail store’s.
As you manage an online and offline store, it's essential to separate inventory quantity across different locations.
Medusa’s multi-warehouse features allow you to manage the inventory items and their availability across locations and sales channels. You can create a sales channel for your online store and a sales channel for your POS system, then manage the inventory quantity of product variants in each of those sales channels. You can also have different sales channels for different retail stores that use the POS system.
Using Medusa's multi-warehouse features, merchants can manage the inventory items and their availability across locations and sales channels. They 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.
When a customer browses your online store and wants to make a purchase, they can only buy items that are available in stock in the location associated with the online store’s channel.
![Using Multi-warehouse features with POS](https://res.cloudinary.com/dza7lstvk/image/upload/v1695115132/Medusa%20Docs/Diagrams/pos-multiwarehouse__1_jscw9e.jpg)
In the POS system, you can use the admin [stock location](https://docs.medusajs.com/api/admin#stock-locations) and [inventory item APIs](https://docs.medusajs.com/api/admin#inventory-items) to check whether an item is available in inventory or not. This helps store operators provide better and quicker customer service.
This also opens the door for other business opportunities, such as an endless aisle experience. If a product isn’t available in-store but is available in other warehouses, you can allow a customer to purchase that item in-store and have it delivered 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. In that case, you can allow customers to purchase that item in-store and deliver it to their address.
<DocCardList colSize={4} items={[
{
@@ -218,13 +214,9 @@ This also opens the door for other business opportunities, such as an endless ai
## Build an Omni-channel Customer Experience
A customer making a purchase in-store should have the same benefits as an online customer. You can find their customer details, if they’re registered in the ecommerce store, and provide them with applicable discounts if necessary.
Using Medusa's Customer APIs and features, you can retrieve a customer's details from the backend and place an order on the POS under their account. The customer can then view their order details on their online profile as if they had placed the order online.
Using Medusa’s Customer APIs and features, you can easily query customers and place an order under their account. The customer can then view their order details on their profile as if they had placed the order online.
In addition, using Medusa’s dynamic discounts feature, store operators can create discounts on the fly for customers using the POS system and apply them to their orders. This improves customer experience and builds customer loyalty.
You can further customize your setup to provide a better customer experience. For example, you can create a rewards system or loyalty points that your customers can benefit from when they make purchases either through the POS system or the online store.
In addition, using Medusa's dynamic discounts feature, store operators can create discounts on the fly for customers using the POS system and apply them to their orders. You can also extend Medusa to provide features for a better customer experience, such as a rewards system or loyalty points.
<DocCardList colSize={6} items={[
{
@@ -251,13 +243,11 @@ You can further customize your setup to provide a better customer experience. Fo
## Accept Payment, Place Order, and Use RMA Features
The first element to placing an order is accepting the customer’s payment. This is handled differently based on the payment methods you want to provide.
Medusa's architecture allows you to integrate any third-party payment processor for your POS and online storefront. For example, you can integrate [Stripe Terminal](https://stripe.com/terminal) to accept in-store payments.
Medusa provides a [manual payment processor](https://github.com/medusajs/medusa/tree/develop/packages/medusa-payment-manual) with a minimal implementation that assumes merchants handle all payment operations manually. Alternatively, you can integrate payment processors that allow you to accept in-store payments, such as [Stripe Terminal](https://stripe.com/terminal), by creating a payment processor.
Once you accept the payment, you can place an order in the POS system using the [Draft Order APIs](https://docs.medusajs.com/api/admin#draft-orders). Draft orders provide similar features to an online checkout experience, including discounts, payment processing, and more.
To place an order in the POS system, you can use the [Draft Order APIs](https://docs.medusajs.com/api/admin#draft-orders). This would allow the store operator to place the order under the customer’s account if they’re registered, and add all the necessary details related to discounts and more, similar to placing an order through the online store.
Using the Medusa admin dashboard, merchants can view all orders coming from different sales channels. This keeps logistics and order handling consistent throughout orders. This also allows customers who place their order in-store to benefit from features like returns and exchanges or swaps that are already available for online store orders.
Then, merchants can view all orders coming from different sales channels using the Medusa admin dashboard. This keeps logistics and order handling consistent and allows businesses to provide return and exchange features to online and in-store customers.
<DocCardList colSize={6} items={[
{