Shahed Nasser
7cb90f8e82
* docs: editing and general fixes of medusa's learning resources * fix build script * update ui dependency * fix build * adjust next.js steps
376 lines
11 KiB
Plaintext
376 lines
11 KiB
Plaintext
import { AcademicCapSolid, UsersSolid } from "@medusajs/icons"
|
||
import { LearningPath } from "docs-ui"
|
||
|
||
export const metadata = {
|
||
title: `B2B Recipe`,
|
||
}
|
||
|
||
# {metadata.title}
|
||
|
||
In this recipe, you'll find resources to guide you in building digital products with Medusa.
|
||
|
||
## Overview
|
||
|
||
In a B2B store, it’s essential to differentiate between customer types to provide them 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.
|
||
|
||
<Note title="Related use-case">
|
||
|
||
[Visionary: Frictionless B2B ecommerce with Medusa](https://medusajs.com/blog/visionary/)
|
||
|
||
</Note>
|
||
|
||
<LearningPath pathName="b2b" />
|
||
|
||
---
|
||
|
||
## Create B2B Sales Channel
|
||
|
||
In Medusa, a sales channel allows you to set product availability per channel. In this case, create a B2B sales channel that includes only B2B products.
|
||
|
||
Create a sales channel through the Medusa Admin or Admin REST APIs.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Option 1: Use Medusa Admin",
|
||
text: "Create the sales channel using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Option 2: Using the REST APIs",
|
||
text: "Create the sales channel using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Create a Publishable API Key
|
||
|
||
Publishable API keys are associated with one or more sales channels. Then, in a client such as a storefront, pass the publishable API key in the header of your requests to ensure all products retrieved belong to the associated sales channel(s).
|
||
|
||
Create a publishable API key through the Medusa Admin or the Admin REST APIs, then associate it with the B2B sales channel. Later, use this key when developing your B2B storefront.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Option 1: Use Medusa Admin",
|
||
text: "Create the publishable API key using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Option 2: Using the REST APIs",
|
||
text: "Create the publishable API key using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Add Products
|
||
|
||
To add B2B products, use the Medusa Admin or the Admin REST APIs. You can also import your products from an existing CSV file using the product-import feature.
|
||
|
||
After or while you add your products, set the products’ availability to the B2B sales channel you’ve created.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Add Products Using Medusa Admin",
|
||
text: "Create the product using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Add Products Using REST APIs",
|
||
text: "Create the product using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Import Products Using Medusa Admin",
|
||
text: "Import the products using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Import Products Using REST APIs",
|
||
text: "Import the product using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Create B2B Customer Groups
|
||
|
||
In B2B sales, you often negotiate special prices with each customer or company. So, you organize your B2B customers into groups that allow you to set different prices for each.
|
||
|
||
You can create a single B2B customer group that all your B2B customers 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 creating the customer groups, 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. It's useful for later steps.
|
||
|
||
For more advanced customer modeling, you may create custom data models. This is covered in the [Create Custom Data Model section](#create-custom-data-model).
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Option 1: Use Medusa Admin",
|
||
text: "Create the customer group using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Option 2: Using the REST APIs",
|
||
text: "Create the customer group using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Add B2B Customers
|
||
|
||
After adding your B2B customer group, add B2B customers and assign them to the B2B customer group. Alternatively, allowing B2B customers to register themselves is covered in a later step.
|
||
|
||
Create a customer through the Medusa Admin or Admin API routes.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Option 1: Use Medusa Admin",
|
||
text: "Create the customers using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Option 2: Using the REST APIs",
|
||
text: "Create the customers using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Create B2B Price List
|
||
|
||
A price list allows you to set different prices on a set of products for various conditions. When building a B2B store, use this to assign different prices for B2B customer groups.
|
||
|
||
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.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Add Price List Using Medusa Admin",
|
||
text: "Create the price list using the Medusa Admin.",
|
||
startIcon: <UsersSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Add Price List Using REST APIs",
|
||
text: "Create the price list using the REST APIs.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Create Custom Data Model
|
||
|
||
To implement a more advanced B2B sales flow, use custom data models such as `Company`, `Employee`, `Admin`, and `Buyer`. This provides more granular control of your B2B sales and allows you to build features like privileges, limits, and more.
|
||
|
||
Each of the data models you create can be managed using custom logic.
|
||
|
||
<Card
|
||
href="#"
|
||
title="Create a Data Model"
|
||
text="Learn how to create a custom data model."
|
||
startIcon={<AcademicCapSolid />}
|
||
showLinkIcon={false}
|
||
/>
|
||
|
||
---
|
||
|
||
## 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'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 API Route checks whether that flag is enabled for the logged-in customer.
|
||
|
||
<Card
|
||
href="#"
|
||
title="Create an API Route"
|
||
text="Learn how to create an API Route in Medusa."
|
||
startIcon={<AcademicCapSolid />}
|
||
showLinkIcon={false}
|
||
/>
|
||
|
||
<Details summaryContent="Example Implementation">
|
||
|
||
For example, create the following API Route that allows you to check the customer’s group and whether it has the `is_b2b` flag enabled:
|
||
|
||
```ts title="src/api/store/customers/is-b2b/route.ts"
|
||
import type {
|
||
CustomerService,
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
export const GET = async (
|
||
req: MedusaRequest,
|
||
res: MedusaResponse
|
||
) => {
|
||
const customerService: CustomerService = req.scope.resolve(
|
||
"customerService"
|
||
)
|
||
|
||
const customer = await customerService
|
||
.retrieve(req.user.customer_id, {
|
||
relations: ["groups"],
|
||
})
|
||
|
||
const is_b2b = customer.groups.some(
|
||
(group) => group.metadata.is_b2b === "true"
|
||
)
|
||
|
||
return res.json({
|
||
is_b2b,
|
||
})
|
||
}
|
||
```
|
||
|
||
Then add the `requireCustomerAuthentication` middleware in `src/api/middlewares.ts` that ensures only authenticated customer can access this API Route:
|
||
|
||
```ts title="src/api/middlewares.ts"
|
||
import {
|
||
requireCustomerAuthentication,
|
||
type MiddlewaresConfig,
|
||
} from "@medusajs/medusa"
|
||
|
||
export const config: MiddlewaresConfig = {
|
||
routes: [
|
||
{
|
||
matcher: "/store/customers/is-b2b",
|
||
middlewares: [requireCustomerAuthentication()],
|
||
},
|
||
],
|
||
}
|
||
```
|
||
|
||
</Details>
|
||
|
||
---
|
||
|
||
## Customize 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.
|
||
|
||
<CardList items={[
|
||
{
|
||
href: "#",
|
||
title: "Create Admin Widget",
|
||
text: "Learn how to add widgets into existing admin pages.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Create Admin UI Routes",
|
||
text: "Learn how to add new pages to your Medusa Admin.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Create Admin Setting Page",
|
||
text: "Learn how to add new page to the Medusa Admin settings.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Customize Storefront
|
||
|
||
You may want different interfaces for B2B and regular customers on the storefront, or to display products differently for each type of customer.
|
||
|
||
Medusa provides a Next.js Starter storefront 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.
|
||
|
||
Use the publishable API key you associated with your B2B sales channel in the storefront to ensure only B2B products are retrieved.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Option 1: Use Next.js Starter",
|
||
text: "Learn how to install and use the Next.js Starter.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Options 2: Build Custom Storefront",
|
||
text: "Learn how to build a custom storefront with your preferred technology.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
<Card
|
||
href="#"
|
||
title="Use Publishable API Keys"
|
||
text="Learn how to use the publishable API key in client requests."
|
||
startIcon={<AcademicCapSolid />}
|
||
showLinkIcon={false}
|
||
className="mt-1"
|
||
/>
|
||
|
||
---
|
||
|
||
## Deploy B2B Store
|
||
|
||
Once you finish your development, deploy your B2B Medusa application and storefront to your preferred hosting providers.
|
||
|
||
<CardList itemsPerRow={2} items={[
|
||
{
|
||
href: "#",
|
||
title: "Deploy Medusa Application",
|
||
text: "Learn how to deploy your Medusa application.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
{
|
||
href: "#",
|
||
title: "Deploy Storefront",
|
||
text: "Learn how to deploy your storefront.",
|
||
startIcon: <AcademicCapSolid />,
|
||
showLinkIcon: false
|
||
},
|
||
]} />
|
||
|
||
---
|
||
|
||
## Additional Development
|
||
|
||
Refer to other guides in the Medusa Resources or the Medusa Book for additional guidance during your development.
|