Split into sections

docs/api-reference/api-reference.mdx

@@ -21,4 +21,4 @@ You can try out **read-only** API version at our [demo playground](https://demo.
 
 ## Guides
 
-In addition to the reference material, you can visit [Guides](../developer/channels) and [API Usage](../api-usage/authentication) pages which include core concepts and best practices to help developers understand the recommended patterns, usage scenarios, and tips for optimizing their GraphQL queries and mutations.
+In addition to the reference material, you can visit [Guides](../developer/channels/overview) and [API Usage](../api-usage/authentication) pages which include core concepts and best practices to help developers understand the recommended patterns, usage scenarios, and tips for optimizing their GraphQL queries and mutations.

docs/developer/channels.mdx → docs/api-reference/channels/api.mdx

@@ -1,45 +1,11 @@
 ---
-title: Channels
-sidebar_label: Channels
+title: Channels API guide
+sidebar_label: API guide
 ---
 
-## Introduction
+## API examples
 
-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.
-
-- 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
-
-Popular use cases:
-
-- 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`
-
-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:
-
-- [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)
-
-Many [Saleor Apps](developer/app-store/overview.mdx) allow to configure them per-channel. We recommend to allow it for the best flexibility.
-
-## 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).
-
-## Getting channel details
+### Getting channel details
 
 Use [`channel`](api-reference/channels/queries/channel.mdx) query to get channel details.
 
@@ -159,7 +125,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 +237,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 +303,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 +404,7 @@ And as a response, we get:
 }
 ```
 
-## Removing a channel
+### Removing a channel
 
 Channels can be removed only when:
 
@@ -450,7 +427,7 @@ input ChannelDeleteInput {
 }
 ```
 
-## Errors
+### Errors
 
 ```graphql
 type ChannelError {