fixes

Author: shahednasser

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

@@ -86,7 +86,10 @@ properties:
       attribute:
         type: string
         title: attribute
-        description: The budget's attribute.
+        description: The cart attribute to limit the budget by.
+        externalDocs:
+          url: >-
+            https://docs.medusajs.com/resources/commerce-modules/promotion/campaign#attribute-based-budgets
   created_at:
     type: string
     format: date-time

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The calculated shipping option's details.
 x-schemaName: AdminCreateCalculatedShippingOption
 required:
   - price_type
@@ -11,37 +11,45 @@ properties:
   price_type:
     type: string
     title: price_type
-    description: The shipping option's price type.
+    description: The calculated shipping option's price type.
+    enum:
+      - calculated
+      - flat
   name:
     type: string
     title: name
-    description: The shipping option's name.
+    description: The calculated shipping option's name.
   service_zone_id:
     type: string
     title: service_zone_id
-    description: The shipping option's service zone id.
+    description: The ID of the associated service zone.
   shipping_profile_id:
     type: string
     title: shipping_profile_id
-    description: The shipping option's shipping profile id.
+    description: The ID of the associated shipping profile.
   data:
     type: object
-    description: The shipping option's data.
+    description: The calculated shipping option's data.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property
   provider_id:
     type: string
     title: provider_id
-    description: The shipping option's provider id.
+    description: >-
+      The ID of the fulfillment provider handling this calculated shipping
+      option.
   type:
     $ref: ./AdminCreateShippingOptionType.yaml
   type_id:
     type: string
     title: type_id
-    description: The shipping option's type id.
+    description: The ID of the shipping option type that this shipping option belongs to.
   rules:
     type: array
-    description: The shipping option's rules.
+    description: The calculated shipping option's rules.
     items:
       $ref: ./AdminCreateShippingOptionRule.yaml
   metadata:
     type: object
-    description: The shipping option's metadata.
+    description: The shipping option's metadata, can hold custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The flat rate shipping option's details.
 x-schemaName: AdminCreateFlatRateShippingOption
 required:
   - price_type
@@ -9,17 +9,48 @@ required:
   - shipping_profile_id
   - provider_id
 properties:
+  name:
+    type: string
+    title: name
+    description: The flat-rate shipping option's name.
+  service_zone_id:
+    type: string
+    title: service_zone_id
+    description: The ID of the associated service zone.
+  shipping_profile_id:
+    type: string
+    title: shipping_profile_id
+    description: The ID of the associated shipping profile.
+  data:
+    type: object
+    description: >-
+      The flat-rate shipping option's data, useful for the fulfillment provider
+      handling its processing.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
   price_type:
     type: string
-    title: price_type
-    description: The shipping option's price type.
+    description: >-
+      The shipping option's price type. If `flat`, the shipping option has a
+      fixed price set in `prices`. Otherwise, the shipping option's price is
+      calculated by the fulfillment provider.
+    enum:
+      - flat
+      - calculated
+  provider_id:
+    type: string
+    title: provider_id
+    description: The ID of the fulfillment provider handling this shipping option.
+  type:
+    $ref: ./AdminCreateShippingOptionType.yaml
   prices:
     type: array
     description: The shipping option's prices.
     items:
       oneOf:
         - type: object
-          description: The price's prices.
+          description: The price's details.
           x-schemaName: AdminCreateShippingOptionPriceWithCurrency
           required:
             - currency_code
@@ -29,6 +60,7 @@ properties:
               type: string
               title: currency_code
               description: The price's currency code.
+              example: usd
             amount:
               type: number
               title: amount
@@ -38,7 +70,7 @@ properties:
               description: The price's rules.
               items:
                 type: object
-                description: The rule's rules.
+                description: The rule's details.
                 x-schemaName: PriceRule
                 required:
                   - attribute
@@ -63,7 +95,7 @@ properties:
                     title: value
                     description: The rule's value.
         - type: object
-          description: The price's prices.
+          description: The price's details.
           x-schemaName: AdminCreateShippingOptionPriceWithRegion
           required:
             - region_id
@@ -72,7 +104,7 @@ properties:
             region_id:
               type: string
               title: region_id
-              description: The price's region id.
+              description: The ID of the region this price is used in.
             amount:
               type: number
               title: amount
@@ -82,7 +114,7 @@ properties:
               description: The price's rules.
               items:
                 type: object
-                description: The rule's rules.
+                description: The rule's details.
                 x-schemaName: PriceRule
                 required:
                   - attribute
@@ -106,31 +138,10 @@ properties:
                     type: number
                     title: value
                     description: The rule's value.
-  name:
-    type: string
-    title: name
-    description: The shipping option's name.
-  service_zone_id:
-    type: string
-    title: service_zone_id
-    description: The shipping option's service zone id.
-  shipping_profile_id:
-    type: string
-    title: shipping_profile_id
-    description: The shipping option's shipping profile id.
-  data:
-    type: object
-    description: The shipping option's data.
-  provider_id:
-    type: string
-    title: provider_id
-    description: The shipping option's provider id.
-  type:
-    $ref: ./AdminCreateShippingOptionType.yaml
   type_id:
     type: string
     title: type_id
-    description: The shipping option's type id.
+    description: The ID of the shipping option type that this shipping option belongs to.
   rules:
     type: array
     description: The shipping option's rules.

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

@@ -19,4 +19,4 @@ properties:
     description: The refund reason's code.
   metadata:
     type: object
-    description: The refund reason's metadata.
+    description: The refund reason's metadata. Can hold custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: The rule's rules.
+description: The details of the shipping option rule.
 x-schemaName: AdminCreateShippingOptionRule
 required:
   - operator
@@ -8,7 +8,7 @@ required:
 properties:
   operator:
     type: string
-    description: The rule's operator.
+    description: The operator used to check whether a rule applies.
     enum:
       - gt
       - lt
@@ -21,15 +21,18 @@ properties:
   attribute:
     type: string
     title: attribute
-    description: The rule's attribute.
+    description: The name of a property or table that the rule applies to.
+    example: customer_group
   value:
     oneOf:
       - type: string
         title: value
-        description: The rule's value.
+        description: A value of the attribute that enables this rule.
+        example: cusgroup_123
       - type: array
-        description: The rule's value.
+        description: Values of the attribute that enable this rule.
         items:
           type: string
           title: value
-          description: The value's details.
+          description: A value of the attribute that enables this rule.
+          example: cusgroup_123

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

@@ -73,6 +73,9 @@ properties:
   metadata:
     type: object
     description: The cart's metadata.
+    externalDocs:
+      url: https://docs.medusajs.com/api/store#manage-metadata
+      description: Learn how to manage metadata
   created_at:
     type: string
     format: date-time

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

@@ -122,6 +122,9 @@ properties:
   metadata:
     type: object
     description: The item's metadata.
+    externalDocs:
+      url: https://docs.medusajs.com/api/store#manage-metadata
+      description: Learn how to manage metadata
   created_at:
     type: string
     format: date-time

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

@@ -1,5 +1,5 @@
 type: object
-description: The tax line's shipping method.
+description: A cart's shipping method.
 x-schemaName: BaseCartShippingMethod
 required:
   - id
@@ -17,7 +17,7 @@ properties:
   cart_id:
     type: string
     title: cart_id
-    description: The shipping method's cart id.
+    description: The ID of the cart this shipping method belongs to.
   name:
     type: string
     title: name
@@ -33,66 +33,78 @@ properties:
   is_tax_inclusive:
     type: boolean
     title: is_tax_inclusive
-    description: The shipping method's is tax inclusive.
+    description: Whether the shipping method's amount is tax inclusive.
   shipping_option_id:
     type: string
     title: shipping_option_id
-    description: The shipping method's shipping option id.
+    description: The ID of the shipping option this method was created from.
   data:
     type: object
-    description: The shipping method's data.
+    description: >-
+      The shipping method's data, useful for fulfillment handling by third-party
+      services.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/resources/commerce-modules/cart/concepts#data-property
   metadata:
     type: object
-    description: The shipping method's metadata.
+    description: The shipping method's metadata, can hold custom key-value pairs.
+    externalDocs:
+      url: https://docs.medusajs.com/api/store#manage-metadata
+      description: Learn how to manage metadata
   tax_lines:
     type: array
     description: The shipping method's tax lines.
     items:
       $ref: ./BaseShippingMethodTaxLine.yaml
   adjustments:
     type: array
-    description: The shipping method's adjustments.
+    description: The shipping method's adjustments, such as applied promotions.
     items:
       $ref: ./BaseShippingMethodAdjustment.yaml
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The shipping method's created at.
+    description: The date the shipping method was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The shipping method's updated at.
+    description: The date the shipping method was updated.
   original_total:
     type: number
     title: original_total
-    description: The shipping method's original total.
+    description: The shipping method's total including taxes, excluding promotions.
   original_subtotal:
     type: number
     title: original_subtotal
-    description: The shipping method's original subtotal.
+    description: The shipping method's total excluding taxes, including promotions.
   original_tax_total:
     type: number
     title: original_tax_total
-    description: The shipping method's original tax total.
+    description: >-
+      The total taxes applied on the shipping method's amount including
+      promotions.
   total:
     type: number
     title: total
-    description: The shipping method's total.
+    description: The shipping method's total amount including taxes and promotions.
   subtotal:
     type: number
     title: subtotal
-    description: The shipping method's subtotal.
+    description: The shipping method's total amount excluding taxes, including promotions.
   tax_total:
     type: number
     title: tax_total
-    description: The shipping method's tax total.
+    description: >-
+      The total taxes applied on the shipping method's amount including
+      promotions.
   discount_total:
     type: number
     title: discount_total
-    description: The shipping method's discount total.
+    description: The total amount discounted.
   discount_tax_total:
     type: number
     title: discount_tax_total
-    description: The shipping method's discount tax total.
+    description: The taxes applied on the discounted amount.