Overview
The Sales Channel Module manages different sales channels for your commerce operations. Sales channels allow you to organize products, orders, and inventory across different storefronts, marketplaces, or distribution channels.
Key Features:
- Multiple sales channel support
- Channel-specific product availability
- Channel-based order tracking
- Inventory management per channel
- Channel metadata and customization
When to Use
Use the Sales Channel Module when you need to:
- Manage multiple storefronts (web, mobile app, etc.)
- Sell on different marketplaces
- Separate B2B and B2C channels
- Track sales by channel
- Control product availability per channel
- Support multi-brand commerce
- Implement channel-specific pricing or promotions
Data Models
SalesChannel
Represents a sales channel or storefront.
Unique sales channel identifier
Sales channel description
Whether the channel is disabled (default: false)
Service Interface
The Sales Channel Module service is available at @medusajs/medusa/sales-channel.
Create Sales Channel
Create a new sales channel.
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
) {
const salesChannelModuleService: ISalesChannelModuleService = req.scope.resolve(
Modules.SALES_CHANNEL
)
const salesChannel = await salesChannelModuleService.createSalesChannels({
name: "Mobile App",
description: "iOS and Android mobile applications",
is_disabled: false,
})
res.json({ sales_channel: salesChannel })
}
data
CreateSalesChannelDTO | CreateSalesChannelDTO[]
required
Sales channel dataSales channel description
Whether to disable the channel
salesChannel
SalesChannelDTO | SalesChannelDTO[]
The created sales channel(s)
Retrieve Sales Channel
Get a sales channel.
const salesChannel = await salesChannelModuleService.retrieveSalesChannel(
"sc_mobile"
)
console.log(salesChannel.name) // "Mobile App"
The ID of the sales channel to retrieve
Configuration for the query
The retrieved sales channel
List Sales Channels
List all sales channels.
const salesChannels = await salesChannelModuleService.listSalesChannels({
is_disabled: false,
})
for (const channel of salesChannels) {
console.log(channel.name)
}
filters
FilterableSalesChannelProps
Filters to applyFilter by sales channel IDs
Filter by disabled status
Update Sales Channel
Modify a sales channel.
const salesChannel = await salesChannelModuleService.updateSalesChannels(
"sc_mobile",
{
description: "Updated mobile app channel",
is_disabled: false,
}
)
ID of the sales channel to update
data
UpdateSalesChannelDTO
required
Delete Sales Channel
Remove a sales channel.
await salesChannelModuleService.deleteSalesChannels(["sc_old"])
Integration Examples
With Product Module
Associate products with sales channels.
import { Modules } from "@medusajs/framework/utils"
const productModule = container.resolve(Modules.PRODUCT)
const salesChannelModule = container.resolve(Modules.SALES_CHANNEL)
// Create sales channels
const webChannel = await salesChannelModule.createSalesChannels({
name: "Website",
})
const appChannel = await salesChannelModule.createSalesChannels({
name: "Mobile App",
})
// Products are linked to sales channels via workflows
// or Link Modules in Medusa
With Cart Module
Create carts for specific channels.
import { Modules } from "@medusajs/framework/utils"
const cartModule = container.resolve(Modules.CART)
const salesChannelModule = container.resolve(Modules.SALES_CHANNEL)
// Get sales channel
const salesChannel = await salesChannelModule.retrieveSalesChannel("sc_web")
// Create cart for channel
const cart = await cartModule.createCarts({
sales_channel_id: salesChannel.id,
currency_code: "usd",
email: "[email protected]",
})
With Order Module
Track orders by sales channel.
import { Modules } from "@medusajs/framework/utils"
const orderModule = container.resolve(Modules.ORDER)
// List orders for specific channel
const orders = await orderModule.listOrders({
sales_channel_id: "sc_mobile",
})
console.log(`${orders.length} orders from mobile app`)
With Inventory Module
Channel-specific inventory availability.
import { Modules } from "@medusajs/framework/utils"
const inventoryModule = container.resolve(Modules.INVENTORY)
// Check inventory available for channel
// (via product-sales channel links)
const availableQuantity = await inventoryModule.retrieveAvailableQuantity(
"iitem_123",
["sloc_warehouse"]
)
Common Use Cases
Multi-Storefront
// Main website
const webChannel = await salesChannelModuleService.createSalesChannels({
name: "Website",
description: "Main e-commerce website",
})
// Mobile app
const appChannel = await salesChannelModuleService.createSalesChannels({
name: "Mobile App",
description: "iOS and Android apps",
})
// Physical stores
const storeChannel = await salesChannelModuleService.createSalesChannels({
name: "Retail Stores",
description: "Point of sale systems in physical locations",
})
Marketplace Integration
// Amazon
const amazonChannel = await salesChannelModuleService.createSalesChannels({
name: "Amazon",
description: "Amazon marketplace integration",
metadata: {
marketplace: "amazon",
seller_id: "ABC123",
},
})
// eBay
const ebayChannel = await salesChannelModuleService.createSalesChannels({
name: "eBay",
description: "eBay marketplace integration",
metadata: {
marketplace: "ebay",
store_name: "MyStore",
},
})
B2B vs B2C
// B2C channel
const b2cChannel = await salesChannelModuleService.createSalesChannels({
name: "Retail",
description: "Direct to consumer sales",
metadata: {
type: "b2c",
},
})
// B2B channel
const b2bChannel = await salesChannelModuleService.createSalesChannels({
name: "Wholesale",
description: "Business to business sales",
metadata: {
type: "b2b",
minimum_order: 1000,
},
})
Multi-Brand
// Brand A
const brandAChannel = await salesChannelModuleService.createSalesChannels({
name: "Brand A Store",
description: "Premium brand storefront",
metadata: {
brand: "brand-a",
},
})
// Brand B
const brandBChannel = await salesChannelModuleService.createSalesChannels({
name: "Brand B Store",
description: "Economy brand storefront",
metadata: {
brand: "brand-b",
},
})
Best Practices
-
Channel Naming: Use clear, descriptive names that identify the channel’s purpose (“Website”, “Mobile App”, “Amazon”, etc.).
-
Metadata Usage: Store channel-specific configuration in metadata:
- API credentials for marketplace integrations
- Channel type (b2b, b2c, marketplace)
- Brand identifiers
- Custom settings
-
Default Channel: Create a default sales channel for your primary storefront during initial setup.
-
Disabled Channels: Use
is_disabled instead of deleting channels to maintain historical data and reporting.
-
Product Availability: Control which products appear in each channel using product-sales channel links (managed via workflows).
-
Analytics: Track performance by channel by filtering orders, carts, and sales data by
sales_channel_id.
-
Channel Context: Always include
sales_channel_id when:
- Creating carts
- Creating orders
- Checking product availability
- Calculating prices