docs: update details on retrieving nested categories (#10317)

www/apps/resources/app/storefront-development/products/categories/nested-categories/page.mdx

@@ -8,7 +8,11 @@ export const metadata = {
 
 A product category has parent and child categories.
 
-To retrieve the child or nested categories of a category in your storefront, pass `*category_children` to the `fields` query parameter of the [Get a Category API Route](!api!/store#product-categories_getproductcategoriesid).
+To retrieve the child or nested categories of a category in your storefront, pass to the [Get a Category API Route](!api!/store#product-categories_getproductcategoriesid) the following query parameters:
+
+- `include_descendants_tree=true` to retrieve each category's nested categories at all levels.
+- Add `category_children` to `fields`, which is the field that will hold a category's nested categories. You can either pass `*category_children` to retrieve all fields of a child category, or specify the fields specifically to avoid a large response size. For example, `field=category_children.id,category_children.name`.
+- `parent_category_id=null` to retrieve only the categories that don't have a parent. This avoids retrieving the child categories multiple times in the response since child categories are now set in their parent's object.
 
 For example:
 
@@ -16,12 +20,16 @@ For example:
   <CodeTab label="Fetch API" value="fetch">
 
 export const fetchHighlights = [
-  ["2", `"*category_children"`, "Select the `category_children` relation."],
+  ["2", `"category_children.id,category_children.name"`, "Select the fields of category children"],
+  ["3", `"include_descendants_tree"`, "Indicate that all nested categories should be retrieved."],
+  ["4", "parent_category_id", "Since each category will have its children, you only retrieve categories that don't have a parent."]
 ]
 
   ```ts highlights={fetchHighlights}
   const searchParams = new URLSearchParams({
-    fields: "*category_children",
+    fields: "category_children.id,category_children.name",
+    include_descendants_tree: true,
+    parent_category_id: null
   })
 
   fetch(`http://localhost:9000/store/product-categories/${id}?${
@@ -44,10 +52,11 @@ export const fetchHighlights = [
 
 export const highlights = [
   ["12", "{ params: { id } }: Params", "This is based on Next.js which passes the path parameters as a prop."],
-  ["24", `"*category_children"`, "Select the `category_children` relation."],
+  ["24", `"category_children.id,category_children.name"`, "Select the fields of category children"],
-  ["27"], ["28"], ["29"], 
+  ["25", "parent_category_id", "Since each category will have its children, you only retrieve categories that don't have a parent."]
-  ["30"], ["31"], ["32"], ["33"], ["34"], ["35"], ["36"], ["37"], ["38"], ["39"],
+  ["26"], ["27"], ["28"], 
-  ["53", "", "Show the nested categories."],
+  ["29"], ["30"], ["31"], ["32"], ["33"], ["34"], ["35"], ["36"], ["37"], ["38"],
+  ["54", "", "Show the nested categories."],
 ]
 
   ```tsx highlights={highlights}
@@ -74,7 +83,8 @@ export const highlights = [
       }
 
       const searchParams = new URLSearchParams({
-        fields: "*category_children",
+        fields: "category_children.id,category_children.name",
+        parent_category_id: null
       })
 
       fetch(`http://localhost:9000/store/product-categories/${id}?${

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

@@ -172,7 +172,7 @@ export const generatedEditDates = {
   "app/storefront-development/customers/retrieve/page.mdx": "2024-09-11T09:55:40.516Z",
   "app/storefront-development/customers/page.mdx": "2024-06-13T12:21:54+03:00",
   "app/storefront-development/products/categories/list/page.mdx": "2024-09-11T10:01:50.873Z",
-  "app/storefront-development/products/categories/nested-categories/page.mdx": "2024-09-11T10:02:28.405Z",
+  "app/storefront-development/products/categories/nested-categories/page.mdx": "2024-11-27T12:00:57.628Z",
   "app/storefront-development/products/categories/products/page.mdx": "2024-09-11T10:08:05.194Z",
   "app/storefront-development/products/categories/retrieve/page.mdx": "2024-09-11T10:04:38.752Z",
   "app/storefront-development/products/categories/page.mdx": "2024-06-11T19:55:56+02:00",

www/utils/generated/oas-output/operations/admin/get_admin_product-categories.ts

@@ -111,20 +111,20 @@
  *             description: A parent category's ID.
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to include the parent category of each category. If enabled, the parent category is set in the `parent_category` property of each category object.
+ *     description: Whether to include the parent category of each category. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to include the parent category of each category. If enabled, the parent category is set in the `parent_category` property of each category object.
+ *       description: Whether to include the parent category of each category. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to include the child categories of each category. If enabled, the child categories are added to the `category_children` property of each category object.
+ *     description: Whether to include the child categories of each category. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to include the child categories of each category. If enabled, the child categories are added to the `category_children` property of each category object.
+ *       description: Whether to include the child categories of each category. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *   - name: is_internal
  *     in: query
  *     description: Filter by whether the category is internal.

www/utils/generated/oas-output/operations/admin/get_admin_product-categories_[id].ts

@@ -25,20 +25,20 @@
  *         url: "#select-fields-and-relations"
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *     description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *       description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *     description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *       description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  * security:
  *   - api_token: []
  *   - cookie_auth: []

www/utils/generated/oas-output/operations/store/get_store_product-categories.ts

@@ -114,20 +114,20 @@
  *             description: A product category's ID.
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *     description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *       description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *     description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the child of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *       description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the child of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *   - name: created_at
  *     in: query
  *     description: Filter by the category's creation date.

www/utils/generated/oas-output/operations/store/get_store_product-categories_[id].ts

@@ -28,20 +28,20 @@
  *         url: "#select-fields-and-relations"
  *   - name: include_ancestors_tree
  *     in: query
- *     description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *     description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_ancestors_tree
- *       description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property.
+ *       description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`.
  *   - name: include_descendants_tree
  *     in: query
- *     description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *     description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  *     required: false
  *     schema:
  *       type: boolean
  *       title: include_descendants_tree
- *       description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property.
+ *       description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL