docs: fix expanding of custom relations in customer and product categ…

…ory routes (#10620)
medusajs · Dec 16, 2024 · 612eb78 · 612eb78
1 parent e8b7035
commit 612eb78
Show file tree

Hide file tree

Showing 26 changed files with 156 additions and 160 deletions.
diff --git a/www/apps/api-reference/specs/admin/openapi.full.yaml b/www/apps/api-reference/specs/admin/openapi.full.yaml
diff --git a/www/apps/api-reference/specs/admin/paths/admin_customers.yaml b/www/apps/api-reference/specs/admin/paths/admin_customers.yaml
@@ -12,7 +12,8 @@ get:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -21,7 +22,8 @@ get:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
     - name: offset
@@ -4221,7 +4223,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -4230,7 +4233,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}.yaml b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}.yaml
@@ -18,7 +18,8 @@ get:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -27,7 +28,8 @@ get:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:
@@ -78,7 +80,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -87,7 +90,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses.yaml b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses.yaml
@@ -18,7 +18,8 @@ get:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -27,7 +28,8 @@ get:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
     - name: offset
@@ -249,7 +251,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -258,7 +261,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses_{address_id}.yaml b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses_{address_id}.yaml
@@ -24,7 +24,8 @@ get:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -33,7 +34,8 @@ get:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:
@@ -92,7 +94,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -101,7 +104,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:
@@ -250,7 +254,8 @@ delete:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -259,7 +264,8 @@ delete:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_customer-groups.yaml b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_customer-groups.yaml
@@ -13,12 +13,13 @@ post:
     - name: fields
       in: query
       description: >-
-        Comma-separated fields that should be included in the returned data.
+        "Comma-separated fields that should be included in the returned data.
 
         if a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields.
 
-        without prefix it will replace the entire default fields.
+        without prefix it will replace the entire default fields. NOTE: This
+        route doesn't allow expanding custom relations."
       required: false
       schema:
         type: string
@@ -27,7 +28,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           If a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. Without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_product-categories.yaml b/www/apps/api-reference/specs/admin/paths/admin_product-categories.yaml
@@ -13,7 +13,8 @@ get:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -22,7 +23,8 @@ get:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
     - name: offset
@@ -677,7 +679,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -686,7 +689,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_product-categories_{id}.yaml b/www/apps/api-reference/specs/admin/paths/admin_product-categories_{id}.yaml
@@ -18,7 +18,8 @@ get:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -27,7 +28,8 @@ get:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
     - name: include_ancestors_tree
@@ -118,7 +120,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -127,7 +130,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/api-reference/specs/admin/paths/admin_product-categories_{id}_products.yaml b/www/apps/api-reference/specs/admin/paths/admin_product-categories_{id}_products.yaml
@@ -17,7 +17,8 @@ post:
         Comma-separated fields that should be included in the returned data. if
         a field is prefixed with `+` it will be added to the default fields,
         using `-` will remove it from the default fields. without prefix it will
-        replace the entire default fields.
+        replace the entire default fields. NOTE: This route doesn't allow
+        expanding custom relations.
       required: false
       schema:
         type: string
@@ -26,7 +27,8 @@ post:
           Comma-separated fields that should be included in the returned data.
           if a field is prefixed with `+` it will be added to the default
           fields, using `-` will remove it from the default fields. without
-          prefix it will replace the entire default fields.
+          prefix it will replace the entire default fields. NOTE: This route
+          doesn't allow expanding custom relations.
         externalDocs:
           url: '#select-fields-and-relations'
   security:

diff --git a/www/apps/resources/app/commerce-modules/customer/extend/page.mdx b/www/apps/resources/app/commerce-modules/customer/extend/page.mdx
@@ -329,43 +329,7 @@ The request will return the customer's details. You'll learn how to retrieve the
 
 When you extend an existing data model through links, you also want to retrieve the custom properties with the data model.
 
-### Retrieve in API Routes
-
-To retrieve the `custom_name` property when you're retrieving the customer through API routes, such as the [Get Customer API Route](!api!/admin#customers_getcustomersid), pass in the `fields` query parameter `+custom.*`, which retrieves the linked `Custom` record's details.
-
-<Note title="Tip">
-
-The `+` prefix in `+custom.*` indicates that the relation should be retrieved with the default customer fields. Learn more about selecting fields and relations in the [API reference](!api!/admin#select-fields-and-relations).
-
-</Note>
-
-For example:
-
-```bash
-curl 'localhost:9000/admin/customers/{customer_id}?fields=+custom.*' \
--H 'Authorization: Bearer {token}'
-```
-
-Make sure to replace `{customer_id}` with the customer's ID, and `{token}` with an admin user's JWT token.
-
-Among the returned `customer` object, you'll find a `custom` property which holds the details of the linked `Custom` record:
-
-```json
-{
-  "customer": {
-    // ...
-    "custom": {
-      "id": "01J9NP7ANXDZ0EAYF0956ZE1ZA",
-      "custom_name": "test",
-      "created_at": "2024-10-08T09:09:06.877Z",
-      "updated_at": "2024-10-08T09:09:06.877Z",
-      "deleted_at": null
-    }
-  }
-}
-```
-
-### Retrieve using Query
+### Retrieve in API Routes using Query
 
 You can also retrieve the `Custom` record linked to a customer in your code using [Query](!docs!/learn/fundamentals/module-links/query).
 
@@ -381,6 +345,8 @@ const { data: [customer] } = await query.graph({
 })
 ```
 
+You can use Query in a custom route to retrieve the customer with its linked `Custom` record.
+
 Learn more about how to use Query in [this guide](!docs!/learn/fundamentals/module-links/query).
 
 ---

diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
@@ -2182,7 +2182,7 @@ export const generatedEditDates = {
   "app/commerce-modules/api-key/links-to-other-modules/page.mdx": "2024-10-08T08:05:36.596Z",
   "app/commerce-modules/cart/extend/page.mdx": "2024-12-11T09:05:37.041Z",
   "app/commerce-modules/cart/links-to-other-modules/page.mdx": "2024-10-08T08:22:35.190Z",
-  "app/commerce-modules/customer/extend/page.mdx": "2024-12-11T09:05:35.368Z",
+  "app/commerce-modules/customer/extend/page.mdx": "2024-12-16T14:11:47.517Z",
   "app/commerce-modules/fulfillment/links-to-other-modules/page.mdx": "2024-10-08T14:58:24.935Z",
   "app/commerce-modules/inventory/links-to-other-modules/page.mdx": "2024-10-08T15:18:30.109Z",
   "app/commerce-modules/pricing/links-to-other-modules/page.mdx": "2024-10-09T13:51:49.986Z",

diff --git a/...nerated/oas-output/operations/admin/delete_admin_customers_[id]_addresses_[address_id].ts b/...nerated/oas-output/operations/admin/delete_admin_customers_[id]_addresses_[address_id].ts
@@ -19,14 +19,14 @@
  *       type: string
  *   - name: fields
  *     in: query
- *     description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
- *       fields. without prefix it will replace the entire default fields.
+ *     description: "Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
+ *       fields. without prefix it will replace the entire default fields. NOTE: This route doesn't allow expanding custom relations."
  *     required: false
  *     schema:
  *       type: string
  *       title: fields
- *       description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
- *         fields. without prefix it will replace the entire default fields.
+ *       description: "Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
+ *         fields. without prefix it will replace the entire default fields. NOTE: This route doesn't allow expanding custom relations."
  *       externalDocs:
  *         url: "#select-fields-and-relations"
  * security: