Sales Channel

[pKorsholm]

Goal

Make it possible for Medusa merchants to segment their product catalog across different channels that drive sales to their business. Examples of Sales Channels could be a website, a physical store, an Amazon marketplace, etc.

User stories

• As a merchant, I want to use Sales Channels to organize my multiple stores in one system.
• As a merchant, I want to be able to create products dedicated to a specific sales channel such as Instagram
• As a store administrator, I want to be able to see which sales channel a given order was created through

What we have

At the moment Medusa doesn’t support multiple Sales Channels. In terms of Sales channels, this means all entities in Medusa could be viewed as belonging to a single Sales Channel.

Initial approach

The first version of Sales Channels will only apply to products and orders, but future iterations will make it possible to control more Medusa resources. In relating to products and orders all logic regarding orders will be adapted to be Sales Channel specific as well. This means that swaps and claims have to be for products of the same sales channel.

We will add a default Sales Channel which encompasses all Medusa entities and the Sales Channel used if no other is specified.

We have chosen a limited set of entities initially because these represent the most limited notion of a Sales Channel in Medusa that still makes sense. This way we can push an initial Sales Channel implementation quickly and extend it in a later iteration.

Sales Channel

Initially, a Sales Channel will be an entity with only a name field besides id, created_at, updated_at, deleted_at.

Initially the Sales Channel entity with related to:

• products
• orders
• carts

Products

A product should be able to belong in many Sales Channels, and should always be available in the default Sales Channel. Editing what Sales Channels a product and its variants belong in should be controllable at the product level, not variant level. In the database, this is supported by a join table connecting Sales Channels and Products. This join table would not have a representative model in the codebase but consist of a product_id and a sales_channel_id as here (though it will not be created):

product_sales_channel { 
	product_id: string 
	sales_channel_id: string 
}

In order to query products in a certain Sales Channel, we will initially implement filters on Sales Channels as query parameters. This will be the initial implementation and is subject to change later as we experiment with different ways of handling Sales Channel queries such as Sales Channel specific API keys.

For this initial implementation all products in a Sales Channel, queried from the store endpoint would look like this:

GET /store/products?channel_id=[channel]

Cart

Carts are included in this set of entities in order to ensure that only products of the same Sales Channel can be added to an order. Since a cart cannot have multiple Sales Channels, the cart Sales Channel will be represented in the cart model as this:

class Cart {
	...

	sales_channel_id: string

	...
}

When a cart is created, a Sales Channel id is passed in the request body. If no id is passed to the cart it will be created in the default Sales Channel.

POST /store/carts 
{ channel_id }

When generating a line item for a cart with a non-default Sales Channel the product that is being added will be validated to check that it is allowed in the Sales Channel of the cart before it gets added.

POST /store/carts/:id/items

Orders

Orders will be included in a Sales Channel when they are created from a cart belonging to a Sales Channel. The order model will also be extended to include a sales_channel_id :

class Order {
	...
	
	sales_channel_id: string

	... 
}

If created from a cart the sales_channel_id of the order will be set to the same sales_channel_id as the cart.

Orders should be filterable by Sales Channel in Medusa Admin. Orders are included in the initial implementation in order to support tracking the origin of an order and to provide insights for Medusa users.

Future aspirations

This discussion is concerned mainly with the initial implementation of Sales Channels. However, some possible future avenues to explore could be:

• Extending Sales Channel with additional entities such as promotions.
• The basis for multi-tenancy in Medusa
• Channel plugins for specific Sales Channels like Amazon, Facebook catalog, etc.

Discussion

How should the existing Medusa instances be migrated to support Sales Channels?

We need to decide how products that haven’t explicitly been assigned a sales channel are handled; you may think of this as the “Default Channel”. We have discussed two options to consider:

• Create a default Sales Channel with the store and assign all existing entities relating to the Sales Channel.
  • This would be the most explicit way of expressing a default Sales Channel.
  • This also creates more overhead in terms of the number of database entities. Especially wrt. products that are connected by a many-to-many relation which would instantly be the size of the product table.
  • If we chose to add a default Sales Channel record. Should we consider adding an is_default flag in order to indicate that a certain channel is the default channel? This would mean that the default channel could also be renamed in order to match the specific term used by the users.
• Decide on the convention that everything is included in the default Sales Channel and that a null Sales Channel id means default Sales Channel (for cart and order)
  • This essentially creates a key for the default Sales Channel that is null
  • This option creates a convention that null means default Sales Channel. Also, the default Sales Channel should be remembered when querying Sales Channels for a specific product.

How to make querying a Sales Channel the best experience

We have discussed several approaches to passing a Sales Channel identifier to the Medusa API. As described above the initial approach we have settled on is to use a query parameter because we deemed it easiest to switch away from using a query parameter.

Other approaches we have discussed are:

• using a specific header

This would make using a singleton client for querying from the store very simple since the header could be set and forgotten. Every subsequent call would then be Sales Channel specific.

• Using a generated API key

Using generated API keys instead of a Sales Channel id would allow users to create multiple keys for each sales channel. This could provide a granular view of each order even in each sales channel.

[inow24]

Hi,
do you plan to make it in a way that sales channels support different pricing per product? In this case, the default sales channel has a base price and each sales channel could have a different price for the same product.

[inow24]

This is to support a b2b scenario whereby a vendor would want to sell a list of products with a base price to some businesses but to be able to update the prices per customer without impacting the base price. So each business would see a different price for the same product.

[srindom]

Cool! That is a great use case for the pricing API I think :)

If you take a look at the price list model (https://github.com/medusajs/medusa/blob/develop/packages/medusa/src/models/price-list.ts#L59), you'll see that it will have a field for Customer Groups. The way this will work is that each price can be tied to a group of customers. If you want to differentiate by individual customers you could just create a customer group with only that one customer.

Do you think this will solve your case?

[inow24]

Thanks for sharing this 👍 ! And Yeah I think it could be a potential solution! Any rough estimation on the availability of the Pricing API, please?

[olivermrbl]

@inow24 The PriceList API has already been released to the core. The UI support in admin will be released early next week 👍

[inow24]

That is great, Oliver! Thank you for sharing and looking forward to the UI support! 👍👍👍

[pKorsholm]

With regard to how existing medusa instances should be handled, as well as how default sales channels should be handled an argument for creating a default sales channel entity is the ability to remove certain products from the default sales channel. The ability to remove a product from the default sales channel would allow merchants to use the default sales channel for a main sales outlet, however if they want to add a specific product for PoS sales channels (such as plastic bags) and not include them in the webshop.

If a product cannot be removed from the default sales channel if would open the possibility for someone to combine products from multiple sales channels, even if they are incompatible (such as a plastic bag in a webshop order).

A different solution to that issue, which also requires a default sales channel object, could be to include functionality to disable sales channels (including the default channel) in order to not force a merchant to have a publicly available default sales channel with all products if they only want specialized sales channels. In the above scenario the merchant would simply have two sales channels, one for PoS and one for the webshop.

Both solutions could work however they are not mutually exclusive.