docs: document different ways of selling products (#11446)

* docs: document different ways of selling products

* add llms

www/apps/resources/app/commerce-modules/inventory/concepts/page.mdx

@@ -14,6 +14,12 @@ The `InventoryItem` data model mainly holds details related to the underlying st
 
 ![A diagram showcasing the relation between data models in the Inventory Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1709658103/Medusa%20Resources/inventory-architecture_kxr2ql.png)
 
+### Inventory Shipping Requirement
+
+An inventory item has a `requires_shipping` field (enabled by default) that indicates whether the item requires shipping. For example, if you're selling a digital license that has limited stock quantity but doesn't require shipping.
+
+When a product variant is purchased in the Medusa application, this field is used to determine whether the item requires shipping. Learn more in [this documentation](../../product/selling-products/page.mdx).
+
 ---
 
 ## InventoryLevel

www/apps/resources/app/commerce-modules/product/selling-products/page.mdx

@@ -0,0 +1,125 @@
+---
+sidebar_label: "Product Shipping Requirement"
+tags:
+    - concept
+    - fulfillment
+---
+
+import { Table } from "docs-ui"
+
+export const metadata = {
+  title: `Configure Selling Products`,
+}
+
+# {metadata.title}
+
+In this guide, you'll learn how to set up and configure your products based on their shipping and inventory requirements, the product type, how you want to sell them, or your commerce ecosystem.
+
+<Note>
+
+The concepts in this guide are applicable starting from Medusa v2.5.1.
+
+</Note>
+
+## Scenario
+
+Businesses can have different selling requirements:
+
+1. They may sell physical or digital items.
+2. They may sell items that don't require shipping or inventory management, such as selling digital products, services, or booking appointments.
+3. They may sell items whose inventory is managed by an external system, such as an ERP.
+
+Medusa supports these different selling requirements by allowing you to configure shipping and inventory requirements for products and their variants. This guide explains how these configurations work, then provides examples of setting up different use cases.
+
+---
+
+## Configuring Shipping Requirements
+
+The Medusa application defines a link between the `Product` data model and a [ShippingProfile](../../fulfillment/concepts/page.mdx#shipping-profile) in the [Fulfillment Module](../../fulfillment/page.mdx), allowing you to associate a product with a shipping profile.
+
+When a product is associated with a shipping profile, its variants require shipping and fulfillment when purchased. This is useful for physical products or digital products that require custom fulfillment.
+
+If a product doesn't have an associated shipping profile, its variants don't require shipping and fulfillment when purchased. This is useful for digital products, for example, that don't require shipping.
+
+### Overriding Shipping Requirements for Variants
+
+A product variant whose inventory is managed by Medusa (its `manage_inventory` property is enabled) has an [inventory item](../../inventory/concepts/page.mdx#inventoryitem). The inventory item has a `requires_shipping` property that can be used to override its shipping requirement. This is useful if the product has an associated shipping profile but you want to disable shipping for a specific variant, or vice versa.
+
+<Note title="Tip">
+
+Learn more about product variant's inventory in [this guide](../variant-inventory/page.mdx).
+
+</Note>
+
+When a product variant is purchased, the Medusa application decides whether the purchased item requires shipping in the following order:
+
+1. The product variant has an inventory item. In this case, the Medusa application uses the inventory item's `requires_shipping` property to determine if the item requires shipping.
+2. If the product variant doesn't have an inventory item, the Medusa application checks whether the product has an associated shipping profile to determine if the item requires shipping.
+
+---
+
+## Use Case Examples
+
+By combining configurations of shipment requirements and inventory management, you can set up your products to support your use case:
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Use Case</Table.HeaderCell>
+      <Table.HeaderCell>Configurations</Table.HeaderCell>
+      <Table.HeaderCell>Example</Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+        Item that's shipped on purchase, and its variant inventory is managed by the Medusa application.
+      </Table.Cell>
+      <Table.Cell>
+        - Product has a shipping profile, or variant inventory item's `requires_shipping` property is `true`.
+        - Product variant's `manage_inventory` property is `true`.
+      </Table.Cell>
+      <Table.Cell>
+        Any stock-kept item (clothing, for example), whose inventory is managed in the Medusa application.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Item that's shipped on purchase, but its variant inventory is managed externally (not by Medusa) or it has infinite stock.
+      </Table.Cell>
+      <Table.Cell>
+        - Product has a shipping profile.
+        - Product variant's `manage_inventory` property is `false`.
+      </Table.Cell>
+      <Table.Cell>
+        Any stock-kept item (clothing, for example), whose inventory is managed in an ERP or has infinite stock.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Item that's not shipped on purchase, but its variant inventory is managed by Medusa.
+      </Table.Cell>
+      <Table.Cell>
+        - Product doesn't have a shipping profile, or variant inventory item's `requires_shipping` property is `false`.
+        - Product variant's `manage_inventory` property is `true`.
+      </Table.Cell>
+      <Table.Cell>
+        Digital products, such as licenses, that don't require shipping but have a limited quantity.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Item that doesn't require shipping and its variant inventory isn't managed by Medusa.
+      </Table.Cell>
+      <Table.Cell>
+        - Product doesn't have a shipping profile, or variant inventory item's `requires_shipping` property is `false`.
+        - Product variant's `manage_inventory` property is `false`.
+      </Table.Cell>
+      <Table.Cell>
+        - Digital products, such as eBooks, that don't require shipping and don't have a stock quantity.
+        - Services, such as appointments, that don't require shipping and don't have a stock quantity.
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+

www/apps/resources/app/commerce-modules/product/variant-inventory/page.mdx

@@ -17,7 +17,7 @@ In this guide, you'll learn about the inventory management features related to p
 
 ## Configure Inventory Management of Product Variants
 
-A product variant, represented by the [ProductVariant](/references/product/models/ProductVariant) data model, has a `manage_inventory` field that's disabled by default. This field indicates whether you'll manage the inventory quantity of the product variant.
+A product variant, represented by the [ProductVariant](/references/product/models/ProductVariant) data model, has a `manage_inventory` field that's disabled by default. This field indicates whether you'll manage the inventory quantity of the product variant in the Medusa application. You can also keep `manage_inventory` disabled if you manage the product's inventory in an external system, such as an ERP.
 
 The Product Module doesn't provide inventory-management features. Instead, the Medusa application uses the [Inventory Module](../../inventory/page.mdx) to manage inventory for products and variants. When `manage_inventory` is disabled, the Medusa application always considers the product variant to be in stock. This is useful if your product's variants aren't items that can be stocked, such as digital products, or they don't have a limited stock quantity.
 
@@ -80,5 +80,6 @@ You can also allow customers to subscribe to restock notifications of a product
 The following guides provide more details on inventory management in the Medusa application:
 
 - [Inventory Kits in the Inventory Module](../../inventory/inventory-kit/page.mdx): Learn how you can implement bundled or multi-part products through the Inventory Module.
+- [Configure Selling Products](../selling-products/page.mdx): Learn how to use inventory management to support different use cases when selling products.
 - [Inventory in Flows](../../inventory/inventory-in-flows/page.mdx): Learn how Medusa utilizes inventory management in different flows.
 - [Storefront guide: how to retrieve a product variant's inventory details](https://docs.medusajs.com/resources/storefront-development/products/inventory).

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

@@ -28,7 +28,7 @@ export const generatedEditDates = {
   "app/commerce-modules/fulfillment/page.mdx": "2025-01-09T13:41:05.614Z",
   "app/commerce-modules/inventory/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/inventory/_events/page.mdx": "2024-07-03T19:27:13+03:00",
-  "app/commerce-modules/inventory/concepts/page.mdx": "2024-10-08T15:11:27.634Z",
+  "app/commerce-modules/inventory/concepts/page.mdx": "2025-02-13T12:37:28.918Z",
   "app/commerce-modules/inventory/inventory-in-flows/page.mdx": "2025-01-08T12:21:12.157Z",
   "app/commerce-modules/inventory/page.mdx": "2025-01-09T13:41:05.212Z",
   "app/commerce-modules/order/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
@@ -5901,7 +5901,7 @@ export const generatedEditDates = {
   "references/core_flows/Order/Steps_Order/variables/core_flows.Order.Steps_Order.updateOrderChangesStepId/page.mdx": "2025-01-27T11:43:49.278Z",
   "app/commerce-modules/payment/account-holder/page.mdx": "2025-01-31T09:37:41.595Z",
   "app/troubleshooting/test-errors/page.mdx": "2025-01-31T13:08:42.639Z",
-  "app/commerce-modules/product/variant-inventory/page.mdx": "2025-02-03T12:19:45.706Z",
+  "app/commerce-modules/product/variant-inventory/page.mdx": "2025-02-13T12:31:51.593Z",
   "app/examples/guides/custom-item-price/page.mdx": "2025-02-07T09:21:11.170Z",
   "references/core_flows/Cart/Steps_Cart/functions/core_flows.Cart.Steps_Cart.validateShippingStep/page.mdx": "2025-02-11T11:36:39.235Z",
   "references/core_flows/Cart/Steps_Cart/variables/core_flows.Cart.Steps_Cart.validateShippingStepId/page.mdx": "2025-02-11T11:36:39.228Z",
@@ -5932,6 +5932,7 @@ export const generatedEditDates = {
   "references/types/types/types.BasePaymentCollectionStatus/page.mdx": "2025-02-11T11:36:50.377Z",
   "references/utils/enums/utils.PaymentActions/page.mdx": "2025-02-11T11:36:54.941Z",
   "references/utils/enums/utils.PaymentCollectionStatus/page.mdx": "2025-02-11T11:36:54.928Z",
+  "app/commerce-modules/product/selling-products/page.mdx": "2025-02-13T13:27:09.270Z",
   "references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.draftOrder/page.mdx": "2025-02-24T10:48:44.721Z",
   "references/js_sdk/admin/Client/methods/js_sdk.admin.Client.throwError_/page.mdx": "2025-02-24T10:48:47.018Z",
   "references/js_sdk/admin/CustomStorage/methods/js_sdk.admin.CustomStorage.getItem/page.mdx": "2025-02-24T10:48:47.069Z",

www/apps/resources/generated/files-map.mjs

@@ -555,6 +555,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/commerce-modules/product/page.mdx",
     "pathname": "/commerce-modules/product"
   },
+  {
+    "filePath": "/www/apps/resources/app/commerce-modules/product/selling-products/page.mdx",
+    "pathname": "/commerce-modules/product/selling-products"
+  },
   {
     "filePath": "/www/apps/resources/app/commerce-modules/product/variant-inventory/page.mdx",
     "pathname": "/commerce-modules/product/variant-inventory"

www/apps/resources/generated/sidebar.mjs

@@ -3225,6 +3225,8 @@ export const generatedSidebar = [
             "type": "category",
             "title": "Concepts",
             "initialOpen": false,
+            "autogenerate_tags": "concept+fulfillment",
+            "autogenerate_as_ref": true,
             "children": [
               {
                 "loaded": true,
@@ -3265,6 +3267,14 @@ export const generatedSidebar = [
                 "path": "/commerce-modules/fulfillment/links-to-other-modules",
                 "title": "Links to Other Modules",
                 "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "ref",
+                "title": "Product Shipping Requirement",
+                "path": "/commerce-modules/product/selling-products",
+                "children": []
               }
             ]
           },
@@ -10588,6 +10598,14 @@ export const generatedSidebar = [
                 "title": "Variant Inventory",
                 "children": []
               },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "path": "/commerce-modules/product/selling-products",
+                "title": "Selling Use Cases",
+                "children": []
+              },
               {
                 "loaded": true,
                 "isPathHref": true,

www/apps/resources/sidebars/fulfillment.mjs

@@ -22,6 +22,8 @@ export const fulfillmentSidebar = [
         type: "category",
         title: "Concepts",
         initialOpen: false,
+        autogenerate_tags: "concept+fulfillment",
+        autogenerate_as_ref: true,
         children: [
           {
             type: "link",

www/apps/resources/sidebars/product.mjs

@@ -25,6 +25,11 @@ export const productSidebar = [
             path: "/commerce-modules/product/variant-inventory",
             title: "Variant Inventory",
           },
+          {
+            type: "link",
+            path: "/commerce-modules/product/selling-products",
+            title: "Selling Use Cases",
+          },
           {
             type: "link",
             path: "/commerce-modules/product/links-to-other-modules",

www/packages/tags/src/tags/concept.ts

@@ -3,6 +3,10 @@ export const concept = [
     "title": "Inventory Kits",
     "path": "/commerce-modules/inventory/inventory-kit"
   },
+  {
+    "title": "Product Shipping Requirement",
+    "path": "/commerce-modules/product/selling-products"
+  },
   {
     "title": "Product Variant Inventory",
     "path": "/commerce-modules/product/variant-inventory"

www/packages/tags/src/tags/fulfillment.ts

@@ -1,4 +1,8 @@
 export const fulfillment = [
+  {
+    "title": "Product Shipping Requirement",
+    "path": "/commerce-modules/product/selling-products"
+  },
   {
     "title": "Checkout Step 3: Choose Shipping Method",
     "path": "/storefront-development/checkout/shipping"

www/packages/tags/src/tags/index.ts

@@ -1,39 +1,39 @@
 export * from "./inventory.js"
-export * from "./pricing.js"
-export * from "./server.js"
 export * from "./query.js"
+export * from "./pricing.js"
 export * from "./tax.js"
+export * from "./fulfillment.js"
+export * from "./server.js"
 export * from "./sales-channel.js"
 export * from "./cart.js"
 export * from "./storefront.js"
+export * from "./payment.js"
+export * from "./customer.js"
 export * from "./stripe.js"
 export * from "./order.js"
-export * from "./fulfillment.js"
-export * from "./customer.js"
-export * from "./auth.js"
-export * from "./js-sdk.js"
+export * from "./product.js"
 export * from "./region.js"
-export * from "./payment.js"
-export * from "./product-collection.js"
+export * from "./js-sdk.js"
+export * from "./checkout.js"
 export * from "./example.js"
-export * from "./api-key.js"
+export * from "./product-category.js"
+export * from "./product-collection.js"
 export * from "./publishable-api-key.js"
+export * from "./auth.js"
+export * from "./api-key.js"
+export * from "./concept.js"
+export * from "./event-bus.js"
 export * from "./step.js"
 export * from "./link.js"
-export * from "./remote-query.js"
 export * from "./workflow.js"
-export * from "./store.js"
-export * from "./checkout.js"
-export * from "./locking.js"
 export * from "./logger.js"
-export * from "./stock-location.js"
-export * from "./promotion.js"
-export * from "./event-bus.js"
-export * from "./user.js"
-export * from "./product.js"
-export * from "./notification.js"
-export * from "./currency.js"
 export * from "./file.js"
-export * from "./product-category.js"
+export * from "./user.js"
+export * from "./promotion.js"
+export * from "./currency.js"
+export * from "./remote-query.js"
 export * from "./admin.js"
-export * from "./concept.js"
+export * from "./stock-location.js"
+export * from "./store.js"
+export * from "./notification.js"
+export * from "./locking.js"