docs: add guide on enforcing sales channel availability in cart + fix to references

www/apps/api-reference/specs/admin/components/schemas/StoreCart.yaml

@@ -45,10 +45,18 @@ properties:
   sales_channel_id:
     type: string
     title: sales_channel_id
-    description: >-
-      The ID of the cart's sales channel. Only products that belong to the same
-      sales channel can be added to the cart. The created order will be
-      associated with the same sales channel.
+    description: >
+      The ID of the cart's sales channel. The created order is associated with
+      the same sales channel.
+
+
+      A product's availability in a sales channel only filters the products you
+      retrieve. Medusa doesn't reject a variant added to the cart when its
+      product isn't available in the cart's sales channel. Refer to the guide in
+      the external documentation to learn how to enforce that validation.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
   email:
     type: string
     title: email

www/apps/api-reference/specs/admin/components/schemas/StoreCreateCart.yaml

@@ -32,10 +32,18 @@ properties:
   sales_channel_id:
     type: string
     title: sales_channel_id
-    description: >-
-      The ID of the sales channel that cart is created in. Only products
-      available in that sales channel can be added to the cart. If not provided,
-      the store's default sales channel is associated with the cart instead.
+    description: >
+      The ID of the sales channel that cart is created in. If not provided, the
+      store's default sales channel is associated with the cart instead.
+
+
+      A product's availability in a sales channel only filters the products you
+      retrieve. Medusa doesn't reject a variant added to the cart when its
+      product isn't available in the cart's sales channel. Refer to the guide in
+      the external documentation to learn how to enforce that validation.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
   metadata:
     type: object
     description: The cart's metadata, can hold custom key-value pairs.

www/apps/api-reference/specs/admin/components/schemas/UpdateCartData.yaml

@@ -15,9 +15,17 @@ properties:
   sales_channel_id:
     type: string
     title: sales_channel_id
-    description: >-
-      The ID of the associated sales channel. Only products available in this
-      channel can be added to the cart.
+    description: >
+      The ID of the associated sales channel.
+
+
+      A product's availability in a sales channel only filters the products you
+      retrieve. Medusa doesn't reject a variant added to the cart when its
+      product isn't available in the cart's sales channel. Refer to the guide in
+      the external documentation to learn how to enforce that validation.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
   email:
     type: string
     title: email

www/apps/api-reference/specs/admin/openapi.full.yaml

@@ -93988,7 +93988,12 @@ components:
         sales_channel_id:
           type: string
           title: sales_channel_id
-          description: The ID of the cart's sales channel. Only products that belong to the same sales channel can be added to the cart. The created order will be associated with the same sales channel.
+          description: |
+            The ID of the cart's sales channel. The created order is associated with the same sales channel.
+
+            A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
+          externalDocs:
+            url: https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
         email:
           type: string
           title: email
@@ -94842,7 +94847,12 @@ components:
         sales_channel_id:
           type: string
           title: sales_channel_id
-          description: The ID of the sales channel that cart is created in. Only products available in that sales channel can be added to the cart. If not provided, the store's default sales channel is associated with the cart instead.
+          description: |
+            The ID of the sales channel that cart is created in. If not provided, the store's default sales channel is associated with the cart instead.
+
+            A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
+          externalDocs:
+            url: https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
         metadata:
           type: object
           description: The cart's metadata, can hold custom key-value pairs.
@@ -98181,7 +98191,12 @@ components:
         sales_channel_id:
           type: string
           title: sales_channel_id
-          description: The ID of the associated sales channel. Only products available in this channel can be added to the cart.
+          description: |
+            The ID of the associated sales channel.
+
+            A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
+          externalDocs:
+            url: https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
         email:
           type: string
           title: email

www/apps/api-reference/specs/store/components/schemas/StoreCart.yaml

@@ -45,10 +45,18 @@ properties:
   sales_channel_id:
     type: string
     title: sales_channel_id
-    description: >-
-      The ID of the cart's sales channel. Only products that belong to the same
-      sales channel can be added to the cart. The created order will be
-      associated with the same sales channel.
+    description: >
+      The ID of the cart's sales channel. The created order is associated with
+      the same sales channel.
+
+
+      A product's availability in a sales channel only filters the products you
+      retrieve. Medusa doesn't reject a variant added to the cart when its
+      product isn't available in the cart's sales channel. Refer to the guide in
+      the external documentation to learn how to enforce that validation.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
   email:
     type: string
     title: email

www/apps/api-reference/specs/store/components/schemas/StoreCreateCart.yaml

@@ -32,10 +32,18 @@ properties:
   sales_channel_id:
     type: string
     title: sales_channel_id
-    description: >-
-      The ID of the sales channel that cart is created in. Only products
-      available in that sales channel can be added to the cart. If not provided,
-      the store's default sales channel is associated with the cart instead.
+    description: >
+      The ID of the sales channel that cart is created in. If not provided, the
+      store's default sales channel is associated with the cart instead.
+
+
+      A product's availability in a sales channel only filters the products you
+      retrieve. Medusa doesn't reject a variant added to the cart when its
+      product isn't available in the cart's sales channel. Refer to the guide in
+      the external documentation to learn how to enforce that validation.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
   metadata:
     type: object
     description: The cart's metadata, can hold custom key-value pairs.

www/apps/api-reference/specs/store/components/schemas/UpdateCartData.yaml

@@ -15,9 +15,17 @@ properties:
   sales_channel_id:
     type: string
     title: sales_channel_id
-    description: >-
-      The ID of the associated sales channel. Only products available in this
-      channel can be added to the cart.
+    description: >
+      The ID of the associated sales channel.
+
+
+      A product's availability in a sales channel only filters the products you
+      retrieve. Medusa doesn't reject a variant added to the cart when its
+      product isn't available in the cart's sales channel. Refer to the guide in
+      the external documentation to learn how to enforce that validation.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
   email:
     type: string
     title: email

www/apps/api-reference/specs/store/openapi.full.yaml

@@ -35909,7 +35909,12 @@ components:
         sales_channel_id:
           type: string
           title: sales_channel_id
-          description: The ID of the cart's sales channel. Only products that belong to the same sales channel can be added to the cart. The created order will be associated with the same sales channel.
+          description: |
+            The ID of the cart's sales channel. The created order is associated with the same sales channel.
+
+            A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
+          externalDocs:
+            url: https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
         email:
           type: string
           title: email
@@ -36763,7 +36768,12 @@ components:
         sales_channel_id:
           type: string
           title: sales_channel_id
-          description: The ID of the sales channel that cart is created in. Only products available in that sales channel can be added to the cart. If not provided, the store's default sales channel is associated with the cart instead.
+          description: |
+            The ID of the sales channel that cart is created in. If not provided, the store's default sales channel is associated with the cart instead.
+
+            A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
+          externalDocs:
+            url: https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
         metadata:
           type: object
           description: The cart's metadata, can hold custom key-value pairs.
@@ -40102,7 +40112,12 @@ components:
         sales_channel_id:
           type: string
           title: sales_channel_id
-          description: The ID of the associated sales channel. Only products available in this channel can be added to the cart.
+          description: |
+            The ID of the associated sales channel.
+
+            A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
+          externalDocs:
+            url: https://docs.medusajs.com/resources/commerce-modules/cart/sales-channel-availability
         email:
           type: string
           title: email

www/apps/book/app/learn/fundamentals/api-routes/errors/page.mdx

@@ -191,7 +191,7 @@ The error object returned in the response has three properties:
       </Table.Cell>
       <Table.Cell>
 
-      Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored in favor of a default message.
+      Indicates that a request conflicts with another previous or ongoing request. The error message in this case is ignored in favor of a default message. Refer to the [note below](#conflict-error-messages) for details.
 
       </Table.Cell>
       <Table.Cell>
@@ -237,6 +237,22 @@ The error object returned in the response has three properties:
   </Table.Body>
 </Table>
 
+### Conflict Error Messages
+
+The error handler replaces the message of a `CONFLICT` error with the following default message:
+
+```plain
+The request conflicted with another request. You may retry the request with the provided Idempotency-Key.
+```
+
+So, only throw a `CONFLICT` error for internal conflicts, such as a request that conflicts with an ongoing transaction or a lock that another process holds. The client doesn't need details about these conflicts, and the default message avoids exposing internal implementation details.
+
+<Note title="Tip">
+
+If the client needs the details of the conflict, throw a `NOT_ALLOWED` error instead. Its message reaches the client, but the response has a `400` status code rather than `409`.
+
+</Note>
+
 ---
 
 ## Override Error Handler

www/apps/book/generated/edit-dates.mjs

@@ -58,7 +58,7 @@ export const generatedEditDates = {
   "app/learn/fundamentals/modules/service-constraints/page.mdx": "2025-03-18T15:12:46.006Z",
   "app/learn/fundamentals/api-routes/responses/page.mdx": "2025-12-30T06:35:16.514Z",
   "app/learn/fundamentals/api-routes/validation/page.mdx": "2025-03-24T06:52:47.896Z",
-  "app/learn/fundamentals/api-routes/errors/page.mdx": "2025-06-19T16:09:08.563Z",
+  "app/learn/fundamentals/api-routes/errors/page.mdx": "2026-07-31T13:22:37.587Z",
   "app/learn/fundamentals/admin/constraints/page.mdx": "2026-07-28T05:43:12.213Z",
   "app/learn/debugging-and-testing/testing-tools/modules-tests/page.mdx": "2025-07-23T15:32:18.008Z",
   "app/learn/fundamentals/module-links/custom-columns/page.mdx": "2025-12-09T13:27:05.446Z",