Add channels

docs/developer/channels.mdx

@@ -3,41 +3,91 @@ title: Channels
 sidebar_label: Channels
 ---
 
-## Introduction
+## What are sales channels
 
-Since version 3.0, Saleor has supported multiple sales channels. This feature allows the shop owner to configure many aspects of the store depending on the channel used.
+Sales channels allow you to model your data across different regions, brands, and business models where data can be customized and shared across different channels. Another way to describe channels is the ability to serve customers and markets differently from a **single backend** instance.
 
-- Your store needs at least one channel to display products
-- You can add as many channels as you need
-- Each channel has precisely one currency
-- Channels can be deactivated for customers
+### Relationships and scope
 
-Popular use cases:
+Adding a channel creates a wide scope of customization options; below is the degree of customization per entity:
 
-- If you sell internationally, you can use separate channels for different currencies or regions
-- If you want to have different prices in the custom mobile app and website, you can set up `website-channel` and `mobile-channel`
+| Entity               | Degree of customization per channel                                               |
+| :------------------- | :-------------------------------------------------------------------------------- |
+| **Checkout**         | Contextualized to a channel to display the appropriate stock, prices, taxes, etc. |
+| **Product**          | Control visibility, availability, search, publication date                        |
+| **Variants**         | Control availability and price                                                    |
+| **Taxes**            | Control calculation methods, gross or net, country exceptions                     |
+| **Vouchers**         | Control availability, discount values, rules                                      |
+| **Orders**           | Contextualized to the channel and required channel permission for access.         |
+| **Promotions**       | Control availability, rules, and pricing                                          |
+| **Payment flow**     | Settings for authorization, payment conditions, expiration, etc.                  |
+| **Currency**         | Channel belongs to a single currency.                                             |
+| **Warehouses**       | Availability                                                                      |
+| **Permission group** | Assigned to channels to control access to sensitive data                          |
+| **Shipping rates**   | Availability, price, order total conditions                                       |
+| **Shipping zones**   | Availability                                                                      |
 
-There are many models you can customize per channel. The details of which fields you can define on a per-channel basis are described in the `ChannelListing` models:
+### How Channels are used
 
-- [Collection](api-reference/products/objects/collection-channel-listing.mdx)
-- [Product](api-reference/products/objects/product-channel-listing.mdx)
-- [ProductVariant](api-reference/products/objects/product-variant-channel-listing.mdx)
-- [Sale](api-reference/discounts/objects/sale-channel-listing.mdx)
-- [ShippingMethod](api-reference/shipping/objects/shipping-method-channel-listing.mdx)
-- [Voucher](api-reference/discounts/objects/voucher-channel-listing.mdx)
+- **Multiple geographical markets:**. Each market has different prices, taxes, shipping options, stock availability, back-office integrations, etc.
 
-Many [Saleor Apps](developer/app-store/overview.mdx) allow to configure them per-channel. We recommend to allow it for the best flexibility.
+- **B2B and B2C:** Customer types can map Channels to grant exclusivity of prices and services.
 
-## Permissions
+- **Different Legal Entities:** Businesses that have different legal entities can restrict access to customer and order data per entity
 
-Listing channels is allowed only for users with the active [`isStaff`](api-reference/users/objects/user.mdx#userisstaffboolean--) flag.
+- **Distribution channels:** Serving physical and online channels
 
-You need the `MANAGE_CHANNELS` permission to create, edit, and remove channels.
-Changing `ChannelListing` does not require additional permissions. For example, changing Product availability requires only `MANAGE_PRODUCTS` permission.
+- **Multi-brand:** Businesses that wish to share customer data, loyalty programs, and products but want separate order data.
 
-Objects with customized per-channel visibility are restricted by channel permissions.
-If a user with restricted channel access fetches per-channel objects, only objects from accessible channels will be returned.
-You can read more about channel permissions [here](developer/permissions.mdx).
+- **A/B testing:** Testing different pricing strategies for product and fulfillment.
+
+- **External channels:** Create dedicated channels for marketplaces or other sales platforms.
+
+### Not ideal for
+
+- Dynamic Currency conversion. Each channel can have a different currency; however, `Checkout` belongs to a single channel, so converting to another channel would not be straightforward. That is because each channel can have different stock, prices, taxes, etc.
+
+- Customer-specific pricing. Potentially, you could serve customers differently using channels, but note that each channel also adds configuration complexity. See [relationships and scope](#relationships-and-scope) for more details.;
+
+- Supplier-specific pricing. If you wish to sell a single product at a different price depending on the supplier, using channels would not work because each checkout is scoped to a single channel; you would have to implement price list functionality instead.
+
+### Channels lifecycle
+
+Your store will have a default channel that can be deleted, but at least one channel is always required.
+
+#### Creation
+
+Channels are assigned to a single currency during creation and can not be changed afterward.
+
+#### Activation
+
+Channels can be activated and deactivated, affecting the channel's discoverability by the front end, which can be useful during the configuration phase.
+
+#### Removal
+
+You must first migrate the existing orders to a channel with the same currency to remove a channel.
+
+### Channel access control
+
+Admin access to order data can be configured on a channel level, this is useful for businesses that have different legal entities that should not have access to each other's data.
+Other objects such as products, vouchers, shipping, can belong to multiple channels at once so their permissions are not scoped per channel to avoid complexity.
+
+### Configuration example
+
+Here is how configuration of a business with many markets would look like:
+
+- `EU` channel. Currency: EUR. Warehouse: Germany. Countries: NL, DE, FR, BE, PT, ES, IT, AT
+- `IRELAND` channel. Currency: EUR. Warehouse: UK, Germany. Because of higher shipping costs and operational costs, new channel is introduced with higher prices and different stock availability.
+- `UK` channel. Currency: GBP. Warehouse: UK. Countries: UK
+- `US` channel. Currency: USD. Warehouse: US. Countries: US, CA, MX. Business operates only in USD in North America and has same product price for all countries, shipping is adjusted per country differently.
+- `B2B` wholesale channel. Currency: USD. Warehouse: Germany, US. Countries: JP, KR, AU. Business operates in USD for wholesale customers in Asia and Australia.
+- `Sister brand` channel. Currency: USD. Warehouse: US. Countries: US, CA, MX. Channel for separate storefront selling different line of product under different brand.
+
+### Data model
+
+![Channels data model](./saleor-channels-data-model.png)
+
+## API examples
 
 ## Getting channel details
 
@@ -159,6 +209,17 @@ Response:
 }
 ```
 
+### Permissions
+
+Listing channels is allowed only for users with the active [`isStaff`](api-reference/users/objects/user.mdx#userisstaffboolean--) flag.
+
+You need the `MANAGE_CHANNELS` permission to create, edit, and remove channels.
+Changing `ChannelListing` does not require additional permissions. For example, changing Product availability requires only `MANAGE_PRODUCTS` permission.
+
+Objects with customized per-channel visibility are restricted by channel permissions.
+If a user with restricted channel access fetches per-channel objects, only objects from accessible channels will be returned.
+You can read more about channel permissions [here](developer/permissions.mdx).
+
 ## Creating a new channel
 
 You can create a new channel using [`channelCreate`](api-reference/channels/mutations/channel-create.mdx) mutation.
@@ -260,7 +321,7 @@ Response:
 }
 ```
 
-### Activate / Deactivate channel
+#### Activate / Deactivate channel
 
 If you want to make the channel unavailable for customers, you can change it's status to `deactivated` using [`channelDeactivate`](api-reference/channels/mutations/channel-deactivate.mdx) mutation:
 
@@ -326,7 +387,7 @@ Response:
 }
 ```
 
-## Reorder warehouses within channels
+### Reorder warehouses within channels
 
 The warehouses assigned to the channel can be sorted. The provided order defines the
 warehouses' order used in `PRIORITIZE_SORTING_ORDER`
@@ -427,7 +488,7 @@ And as a response, we get:
 }
 ```
 
-## Removing a channel
+### Removing a channel
 
 Channels can be removed only when:
 
@@ -450,7 +511,7 @@ input ChannelDeleteInput {
 }
 ```
 
-## Errors
+### Errors
 
 ```graphql
 type ChannelError {

versioned_docs/version-3.x/developer/channels.mdx

@@ -3,43 +3,93 @@ title: Channels
 sidebar_label: Channels
 ---
 
-## Introduction
+## What are sales channels
 
-Since version 3.0, Saleor has supported multiple sales channels. This feature allows the shop owner to configure many aspects of the store depending on the channel used.
+Sales channels allow you to model your data across different regions, brands, and business models where data can be customized and shared across different channels. Another way to describe channels is the ability to serve customers and markets differently from a **single backend** instance.
 
-- Your store needs at least one channel to display products
-- You can add as many channels as you need
-- Each channel has precisely one currency
-- Channels can be deactivated for customers
+### Relationships and scope
 
-Popular use cases:
+Adding a channel creates a wide scope of customization options; below is the degree of customization per entity:
 
-- If you sell internationally, you can use separate channels for different currencies or regions
-- If you want to have different prices in the custom mobile app and website, you can set up `website-channel` and `mobile-channel`
+| Entity               | Degree of customization per channel                                               |
+| :------------------- | :-------------------------------------------------------------------------------- |
+| **Checkout**         | Contextualized to a channel to display the appropriate stock, prices, taxes, etc. |
+| **Product**          | Control visibility, availability, search, publication date                        |
+| **Variants**         | Control availability and price                                                    |
+| **Taxes**            | Control calculation methods, gross or net, country exceptions                     |
+| **Vouchers**         | Control availability, discount values, rules                                      |
+| **Orders**           | Contextualized to the channel and required channel permission for access.         |
+| **Promotions**       | Control availability, rules, and pricing                                          |
+| **Payment flow**     | Settings for authorization, payment conditions, expiration, etc.                  |
+| **Currency**         | Channel belongs to a single currency.                                             |
+| **Warehouses**       | Availability                                                                      |
+| **Permission group** | Assigned to channels to control access to sensitive data                          |
+| **Shipping rates**   | Availability, price, order total conditions                                       |
+| **Shipping zones**   | Availability                                                                      |
 
-There are many models you can customize per channel. The details of which fields you can define on a per-channel basis are described in the `ChannelListing` models:
+### How Channels are used
 
-- [Collection](api-reference/products/objects/collection-channel-listing.mdx)
-- [Product](api-reference/products/objects/product-channel-listing.mdx)
-- [ProductVariant](api-reference/products/objects/product-variant-channel-listing.mdx)
-- [Sale](api-reference/discounts/objects/sale-channel-listing.mdx)
-- [ShippingMethod](api-reference/shipping/objects/shipping-method-channel-listing.mdx)
-- [Voucher](api-reference/discounts/objects/voucher-channel-listing.mdx)
+- **Multiple geographical markets:**. Each market has different prices, taxes, shipping options, stock availability, back-office integrations, etc.
 
-Many [Saleor Apps](developer/app-store/overview.mdx) allow to configure them per-channel. We recommend to allow it for the best flexibility.
+- **B2B and B2C:** Customer types can map Channels to grant exclusivity of prices and services.
 
-## Permissions
+- **Different Legal Entities:** Businesses that have different legal entities can restrict access to customer and order data per entity
 
-Listing channels is allowed only for users with the active [`isStaff`](api-reference/users/objects/user.mdx#userisstaffboolean--) flag.
+- **Distribution channels:** Serving physical and online channels
 
-You need the `MANAGE_CHANNELS` permission to create, edit, and remove channels.
-Changing `ChannelListing` does not require additional permissions. For example, changing Product availability requires only `MANAGE_PRODUCTS` permission.
+- **Multi-brand:** Businesses that wish to share customer data, loyalty programs, and products but want separate order data.
 
-Objects with customized per-channel visibility are restricted by channel permissions.
-If a user with restricted channel access fetches per-channel objects, only objects from accessible channels will be returned.
-You can read more about channel permissions [here](developer/permissions.mdx).
+- **A/B testing:** Testing different pricing strategies for product and fulfillment.
+
+- **External channels:** Create dedicated channels for marketplaces or other sales platforms.
+
+### Not ideal for
+
+- Dynamic Currency conversion. Each channel can have a different currency; however, `Checkout` belongs to a single channel, so converting to another channel would not be straightforward. That is because each channel can have different stock, prices, taxes, etc.
+
+- Customer-specific pricing. Potentially, you could serve customers differently using channels, but note that each channel also adds configuration complexity. See [relationships and scope](#relationships-and-scope) for more details.;
+
+- Supplier-specific pricing. If you wish to sell a single product at a different price depending on the supplier, using channels would not work because each checkout is scoped to a single channel; you would have to implement price list functionality instead.
+
+### Channels lifecycle
+
+Your store will have a default channel that can be deleted, but at least one channel is always required.
+
+#### Creation
+
+Channels are assigned to a single currency during creation and can not be changed afterward.
+
+#### Activation
+
+Channels can be activated and deactivated, affecting the channel's discoverability by the front end, which can be useful during the configuration phase.
+
+#### Removal
+
+You must first migrate the existing orders to a channel with the same currency to remove a channel.
 
-## Getting channel details
+### Channel access control
+
+Admin access to order data can be configured on a channel level, this is useful for businesses that have different legal entities that should not have access to each other's data.
+Other objects such as products, vouchers, shipping, can belong to multiple channels at once so their permissions are not scoped per channel to avoid complexity.
+
+### Configuration example
+
+Here is how configuration of a business with many markets would look like:
+
+- `EU` channel. Currency: EUR. Warehouse: Germany. Countries: NL, DE, FR, BE, PT, ES, IT, AT
+- `IRELAND` channel. Currency: EUR. Warehouse: UK, Germany. Because of higher shipping costs and operational costs, new channel is introduced with higher prices and different stock availability.
+- `UK` channel. Currency: GBP. Warehouse: UK. Countries: UK
+- `US` channel. Currency: USD. Warehouse: US. Countries: US, CA, MX. Business operates only in USD in North America and has same product price for all countries, shipping is adjusted per country differently.
+- `B2B` wholesale channel. Currency: USD. Warehouse: Germany, US. Countries: JP, KR, AU. Business operates in USD for wholesale customers in Asia and Australia.
+- `Sister brand` channel. Currency: USD. Warehouse: US. Countries: US, CA, MX. Channel for separate storefront selling different line of product under different brand.
+
+### Data model
+
+![Channels data model](./saleor-channels-data-model.png)
+
+## API examples
+
+### Getting channel details
 
 Use [`channel`](api-reference/channels/queries/channel.mdx) query to get channel details.
 
@@ -159,7 +209,18 @@ Response:
 }
 ```
 
-## Creating a new channel
+### Permissions
+
+Listing channels is allowed only for users with the active [`isStaff`](api-reference/users/objects/user.mdx#userisstaffboolean--) flag.
+
+You need the `MANAGE_CHANNELS` permission to create, edit, and remove channels.
+Changing `ChannelListing` does not require additional permissions. For example, changing Product availability requires only `MANAGE_PRODUCTS` permission.
+
+Objects with customized per-channel visibility are restricted by channel permissions.
+If a user with restricted channel access fetches per-channel objects, only objects from accessible channels will be returned.
+You can read more about channel permissions [here](developer/permissions.mdx).
+
+### Creating a new channel
 
 You can create a new channel using [`channelCreate`](api-reference/channels/mutations/channel-create.mdx) mutation.
 During checkout creation, you can define the allocation strategy. Right now the
@@ -260,9 +321,9 @@ Response:
 }
 ```
 
-### Activate / Deactivate channel
+#### Activate / Deactivate channel
 
-If you want to make the channel unavailable for customers, you can change it's status to `deactivated` using [`channelDeactivate`](api-reference/channels/mutations/channel-deactivate.mdx) mutation:
+If you want to make the channel unavailable for customers, you can change its status to `deactivated` using [`channelDeactivate`](api-reference/channels/mutations/channel-deactivate.mdx) mutation:
 
 ```graphql
 mutation {
@@ -326,7 +387,7 @@ Response:
 }
 ```
 
-## Reorder warehouses within channels
+### Reorder warehouses within channels
 
 The warehouses assigned to the channel can be sorted. The provided order defines the
 warehouses' order used in `PRIORITIZE_SORTING_ORDER`
@@ -427,7 +488,7 @@ And as a response, we get:
 }
 ```
 
-## Removing a channel
+### Removing a channel
 
 Channels can be removed only when:
 
@@ -450,7 +511,7 @@ input ChannelDeleteInput {
 }
 ```
 
-## Errors
+### Errors
 
 ```graphql
 type ChannelError {