docs: edits and fixes to commerce module docs (#7468)
Apply edits and fixes to the commerce modules docs
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
130de74d6d
commit
2c5ba408d4
160 files changed
+6400
-3790
No files matched your search
@@ -8,4 +8,10 @@ export const metadata = {
|
||||
|
||||
Find in this reference the list of events emitted by the Sales Channel Module.
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Events are still in development, so this reference will change in the future.
|
||||
|
||||
</Note>
|
||||
|
||||
<EventsTable />
|
||||
@@ -26,7 +26,7 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
request.scope.resolve(ModuleRegistrationName.SALES_CHANNEL)
|
||||
|
||||
const salesChannel = await salesChannelModuleService.create({
|
||||
name: request.body.name,
|
||||
name: "B2B",
|
||||
})
|
||||
|
||||
res.json({
|
||||
@@ -48,10 +48,9 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
export async function POST(request: Request) {
|
||||
const salesChannelModuleService =
|
||||
await initializeSalesChannelModule()
|
||||
const body = await request.json()
|
||||
|
||||
const salesChannel = await salesChannelModuleService.create({
|
||||
name: body.name,
|
||||
name: "B2B",
|
||||
})
|
||||
|
||||
return NextResponse.json({ sales_channel: salesChannel })
|
||||
@@ -129,7 +128,7 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
request.scope.resolve(ModuleRegistrationName.SALES_CHANNEL)
|
||||
|
||||
const salesChannel = await salesChannelModuleService.retrieve(
|
||||
request.params.id
|
||||
"sc_123"
|
||||
)
|
||||
|
||||
res.json({
|
||||
@@ -148,22 +147,14 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
initialize as initializeSalesChannelModule,
|
||||
} from "@medusajs/sales-channel"
|
||||
|
||||
type ContextType = {
|
||||
params: {
|
||||
id: string
|
||||
}
|
||||
}
|
||||
|
||||
export async function GET(
|
||||
request: Request,
|
||||
{ params }: ContextType
|
||||
request: Request
|
||||
) {
|
||||
const salesChannelModuleService =
|
||||
await initializeSalesChannelModule()
|
||||
const body = await request.json()
|
||||
|
||||
const salesChannel = await salesChannelModuleService.retrieve(
|
||||
params.id
|
||||
"sc_123"
|
||||
)
|
||||
|
||||
return NextResponse.json({ sales_channel: salesChannel })
|
||||
@@ -193,8 +184,8 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
request.scope.resolve(ModuleRegistrationName.SALES_CHANNEL)
|
||||
|
||||
const salesChannel = await salesChannelModuleService.update({
|
||||
id: request.params.id,
|
||||
description: request.body.description,
|
||||
id: "sc_123",
|
||||
description: "Sales channel for B2B customers",
|
||||
})
|
||||
|
||||
res.json({
|
||||
@@ -213,23 +204,15 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
initialize as initializeSalesChannelModule,
|
||||
} from "@medusajs/sales-channel"
|
||||
|
||||
type ContextType = {
|
||||
params: {
|
||||
id: string
|
||||
}
|
||||
}
|
||||
|
||||
export async function POST(
|
||||
request: Request,
|
||||
{ params }: ContextType
|
||||
request: Request
|
||||
) {
|
||||
const salesChannelModuleService =
|
||||
await initializeSalesChannelModule()
|
||||
const body = await request.json()
|
||||
|
||||
const salesChannel = await salesChannelModuleService.update({
|
||||
id: params.id,
|
||||
description: body.description,
|
||||
id: "sc_123",
|
||||
description: "Sales channel for B2B customers",
|
||||
})
|
||||
|
||||
return NextResponse.json({ sales_channel: salesChannel })
|
||||
@@ -258,7 +241,7 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
const salesChannelModuleService: ISalesChannelModuleService =
|
||||
request.scope.resolve(ModuleRegistrationName.SALES_CHANNEL)
|
||||
|
||||
await salesChannelModuleService.delete(request.params.id)
|
||||
await salesChannelModuleService.delete("sc_123")
|
||||
|
||||
res.status(200)
|
||||
}
|
||||
@@ -274,20 +257,13 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
initialize as initializeSalesChannelModule,
|
||||
} from "@medusajs/sales-channel"
|
||||
|
||||
type ContextType = {
|
||||
params: {
|
||||
id: string
|
||||
}
|
||||
}
|
||||
|
||||
export async function DELETE(
|
||||
request: Request,
|
||||
{ params }: ContextType
|
||||
request: Request
|
||||
) {
|
||||
const salesChannelModuleService =
|
||||
await initializeSalesChannelModule()
|
||||
|
||||
await salesChannelModuleService.delete(params.id)
|
||||
await salesChannelModuleService.delete("sc_123")
|
||||
}
|
||||
```
|
||||
|
||||
@@ -298,4 +274,4 @@ In this guide, you’ll find common examples of how you can use the Sales Channe
|
||||
|
||||
## More Examples
|
||||
|
||||
The [Sales Channel Module interface reference](/references/sales-channel) provides a reference to all the methods available for use with examples for each.
|
||||
The [Sales Channel Module's main service reference](/references/sales-channel) provides a reference to all the methods available for use with examples for each.
|
||||
@@ -16,7 +16,7 @@ Some use case examples for using a sales channel:
|
||||
|
||||
- Implement a B2B Ecommerce Store.
|
||||
- Specify different products for each channel you sell in.
|
||||
- Support Omnichannel in your ecommerce store.
|
||||
- Support omnichannel in your ecommerce store.
|
||||
|
||||
---
|
||||
|
||||
@@ -24,9 +24,7 @@ Some use case examples for using a sales channel:
|
||||
|
||||
### Sales Channel Management
|
||||
|
||||
Store and manage sales channels in your store.
|
||||
|
||||
Each sales channel has different meta information such as name or description, allowing you to easily differentiate between sales channels.
|
||||
Manage sales channels in your store. Each sales channel has different meta information such as name or description, allowing you to easily differentiate between sales channels.
|
||||
|
||||
```ts
|
||||
const salesChannels = await salesChannelModuleService.create([
|
||||
@@ -41,7 +39,7 @@ const salesChannels = await salesChannelModuleService.create([
|
||||
|
||||
### Product Availability
|
||||
|
||||
By combining the Product and Sales Channel modules, you can specify a product's availability per sales channel.
|
||||
Medusa links the Product and Sales Channel modules, allowing merchants to specify a product's availability per sales channel.
|
||||
|
||||
For example, B2B customers viewing products only see products in the B2B sales channel.
|
||||
|
||||
@@ -55,14 +53,16 @@ Orders are also scoped to a sales channel due to the relation between the Sales
|
||||
|
||||
## Configure Sales Channel Module
|
||||
|
||||
After installing the `@medusajs/sales-channel` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
|
||||
To use the Sales Channel Module, enable it in the `modules` object in `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const { Modules } = require("@medusajs/modules-sdk")
|
||||
|
||||
// ...
|
||||
|
||||
const modules = {
|
||||
// ...
|
||||
salesChannel: {
|
||||
resolve: "@medusajs/sales-channel",
|
||||
},
|
||||
[Modules.SALES_CHANNEL]: true,
|
||||
}
|
||||
```
|
||||
|
||||
@@ -121,11 +121,14 @@ For example:
|
||||
import { ISalesChannelModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
const step1 = createStep("step-1", async (_, context) => {
|
||||
const step1 = createStep(
|
||||
"step-1",
|
||||
async (_, { container }) => {
|
||||
const salesChannelModuleService: ISalesChannelModuleService =
|
||||
context.container.resolve(
|
||||
container.resolve(
|
||||
ModuleRegistrationName.SALES_CHANNEL
|
||||
)
|
||||
|
||||
const salesChannels = await salesChannelModuleService.list()
|
||||
})
|
||||
```
|
||||
|
||||
+4
-46
@@ -12,7 +12,7 @@ In this document, you’ll learn what publishable API keys are and how to use th
|
||||
|
||||
When using multiple sales channels, you’ll need to specify the ID of a storefront’s sales channel. This ensures that you retrieve the products available in that sales channel and associate the sales channel with the storefront’s carts and orders.
|
||||
|
||||
The Store API routes accept the sales channel’s IDs differently. For example, the [List Products API route](https://docs.medusajs.com/api/store#products) accepts the sales channel’s ID as a query parameter, whereas the [Create Cart API route](https://docs.medusajs.com/api/store#carts_postcart) accepts it in the request’s body.
|
||||
The [Store API routes](!api!/store) accept the sales channel’s IDs differently depending on the API route's HTTP method. Some accept it as a query parameter whereas others accept it as a request body parameter.
|
||||
|
||||
This approach is tedious and error-prone as your storefront scales and as you develop multiple types of storefronts.
|
||||
|
||||
@@ -20,59 +20,17 @@ This approach is tedious and error-prone as your storefront scales and as you de
|
||||
|
||||
## Introducing Publishable API Keys
|
||||
|
||||
The API Key module allows you to create keys for different usages. One of those usages is to create a publishable API key.
|
||||
A publishable API key, provided by the API Key Module, is a client key scoped to one or more sales channels. When passed in the header of a request, the Medusa application infers the associated sales channels.
|
||||
|
||||
A publishable API key is a client key scoped to one or more sales channels. When passed in the header of a request, the Medusa application infers the associated sales channels.
|
||||
|
||||
So, instead of the previous approach of manually passing the sales channel’s ID based on the API route, you always pass the publishable API key in the header of your requests:
|
||||
So, instead of the approach, indicated in the previous section, of manually passing the sales channel’s ID based on the API route, you always pass the publishable API key in the header of your requests:
|
||||
|
||||
```bash
|
||||
curl http://localhost:9000/store/products \
|
||||
x-publishable-api-key: {your_publishable_api_key}
|
||||
```
|
||||
|
||||
The Medusa JS Client and Medusa React both provide the option to pass the publishable API key during initialization:
|
||||
|
||||
<CodeTabs groupId="client-id">
|
||||
<CodeTab label="JS Client" value="js-client">
|
||||
|
||||
```ts
|
||||
const medusa = new Medusa({
|
||||
maxRetries: 3,
|
||||
baseUrl: "http://localhost:9000",
|
||||
publishableApiKey,
|
||||
})
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="Medusa React" value="medusa-react">
|
||||
|
||||
```tsx
|
||||
import { MedusaProvider } from "medusa-react"
|
||||
|
||||
// define query client...
|
||||
|
||||
const App = () => {
|
||||
return (
|
||||
<MedusaProvider
|
||||
queryClientProviderProps={{ client: queryClient }}
|
||||
baseUrl="http://localhost:9000"
|
||||
// ...
|
||||
publishableApiKey={publishableApiKey}
|
||||
>
|
||||
<MyStorefront />
|
||||
</MedusaProvider>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
</CodeTabs>
|
||||
|
||||
Then, all requests using the client/hooks automatically include the publishable API key in the header.
|
||||
|
||||
---
|
||||
|
||||
## How to Create a Publishable API Key?
|
||||
|
||||
To create a publishable API key, either use the Medusa Admin or the [Admin API Routes](https://docs.medusajs.com/api/admin#publishable-api-keys).
|
||||
To create a publishable API key, either use the Medusa Admin or the [Admin API Routes](!api!/admin#publishable-api-keys).
|
||||
+22
-16
@@ -4,25 +4,23 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
When Commerce Modules are used together in a Medusa application, the Medusa application handles building the relations between these modules.
|
||||
This document showcases the link modules defined between the Sales Channel Module and other commerce modules.
|
||||
|
||||
This document showcases the relation between the Sales Channel Module and other Commerce Modules.
|
||||
## API Key Module
|
||||
|
||||
## Product Module
|
||||
A publishable API key allows you to easily specify the sales channel scope in a client request. Medusa defines a link module that builds a relationship between the `ApiKey` and the `SalesChannel` data models.
|
||||
|
||||
A product has different availability for different sales channels. The Medusa application forms a relation between the `Product` and the `SalesChannel` data models.
|
||||
|
||||
|
||||
A product can be available in more than one sales channel. Then, you can retrieve only the products of a sales channel.
|
||||
|
||||
|
||||
Using the API Key Module, you create a publishable key and associate it with a sales channel. Learn more in [this document](../publishable-api-keys/page.mdx)
|
||||
|
||||
---
|
||||
|
||||
## Cart Module
|
||||
|
||||
A cart is associated with the sales channel it's created in. The Medusa application forms a relation between the `Cart` and the `SalesChannel` data models.
|
||||
A cart is associated with the sales channel it's created in. Medusa defines a link module that builds a relationship between the `Cart` and the `SalesChannel` data models.
|
||||
|
||||
|
||||
|
||||
|
||||
For example, if a customer adds an item to the cart in a mobile app, the cart is associated with the mobile app's sales channel. However, if a customer adds an item to the cart in a web storefront, the cart is associated with the storefront's sales channel.
|
||||
|
||||
@@ -30,20 +28,28 @@ For example, if a customer adds an item to the cart in a mobile app, the cart is
|
||||
|
||||
## Order Module
|
||||
|
||||
An order is associated with the sales channel it's created in. The Medusa application forms a relation between the `Order` and the `SalesChannel` data models.
|
||||
An order is associated with the sales channel it's created in. Medusa defines a link module that builds a relationship between the `Order` and the `SalesChannel` data models.
|
||||
|
||||
|
||||
|
||||
|
||||
For example, if an order is created in a mobile app, it'll be associated with its sales channel. If another order is created through a POS system, it'll be associated with the POS's sales channel.
|
||||
|
||||
---
|
||||
|
||||
## API Key Module
|
||||
## Product Module
|
||||
|
||||
A publishable API key allows you to easily specify the sales channel scope in a client request. The Medusa application forms a relation between the `ApiKey` and the `SalesChannel` data models.
|
||||
A product has different availability for different sales channels. Medusa defines a link module that builds a relationship between the `Product` and the `SalesChannel` data models.
|
||||
|
||||
|
||||
A product can be available in more than one sales channel. Then, you can retrieve only the products of a sales channel.
|
||||
|
||||
Using the API Key Module, you create a publishable key and associate it with a sales channel.
|
||||
|
||||
|
||||
Instead of passing the sales channel's ID in every request either in the query or body parameters, you always pass the API key in the header of your requests. The Medusa application then infers the sales channel scope from it.
|
||||
---
|
||||
|
||||
## Stock Location Module
|
||||
|
||||
A stock location is associated with a sales channel. This scopes inventory quantities associated with that stock location by the associated sales channel.
|
||||
|
||||
Medusa defines a link module that builds a relationship between the `SalesChannel` and `StockLocation` data models.
|
||||
|
||||
|
||||
Reference in new issue
Block a user