chore(docs): Updated API Reference (v2) (#9437)

Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action

Co-authored-by: Shahed Nasser <27354907+shahednasser@users.noreply.github.com>

packages/cli/oas/medusa-oas-cli/redocly/redocly-config.yaml

@@ -22,6 +22,7 @@ decorators:
         - AdminProduct
       BaseProduct:
         - BaseProduct
+        - BaseProductVariant
       StoreProduct:
         - StoreProductCategory
         - StoreProduct
@@ -107,6 +108,29 @@ decorators:
         - BaseProduct
       OrderItem:
         - OrderLineItem
+      AdminOrderChangeAction:
+        - AdminOrderChange
+      AdminPaymentSession:
+        - AdminPaymentCollection
+      AdminProductOption:
+        - AdminProduct
+        - AdminProductOptionValue
+      AdminPromotion:
+        - AdminApplicationMethod
+      BaseOrderItemDetail:
+        - BaseOrderLineItem
+      BaseOrderShippingDetail:
+        - BaseOrderShippingMethod
+      StorePaymentSession:
+        - StorePaymentCollection
+      StoreProductOption:
+        - StoreProduct
+      StoreProductOptionValue:
+        - StoreProductOption
+      AdminPayment:
+        - AdminPaymentCollection
+      StoreProductVariant:
+        - StoreProduct
 theme:
   openapi:
     theme:

www/apps/api-reference/specs/admin/code_samples/Bash/auth_user_{auth_provider}/post.sh

@@ -0,0 +1 @@
+curl -X POST '{backend_url}/auth/user/google'

www/apps/api-reference/specs/admin/code_samples/Bash/auth_user_{auth_provider}_callback/post.sh

@@ -0,0 +1 @@
+curl -X POST '{backend_url}/auth/user/github/callback?code=123'

www/apps/api-reference/specs/admin/code_samples/Shell/admin_orders_{id}_fulfillments_{fulfillment_id}_mark-as-delivered/post.sh

@@ -0,0 +1,2 @@
+curl -X POST '{backend_url}/admin/orders/{id}/fulfillments/{fulfillment_id}/mark-as-delivered' \
+-H 'Authorization: Bearer {access_token}'

www/apps/api-reference/specs/admin/code_samples/Shell/admin_shipping-options_{id}/get.sh

@@ -0,0 +1,2 @@
+curl '{backend_url}/admin/shipping-options/{id}' \
+-H 'Authorization: Bearer {access_token}'

www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}/post.sh

@@ -1 +1,6 @@
-curl -X POST '{backend_url}/auth/user/github'
+curl -X POST '{backend_url}/auth/user/emailpass' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "admin@medusa-test.com",
+  "password": "supersecret"
+}'

www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_callback/post.sh

@@ -1 +1 @@
-curl -X POST '{backend_url}/auth/user/github/callback?code=123'
+curl -X POST '{backend_url}/auth/user/google/callback?code=123'

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

@@ -1,45 +1,40 @@
 type: object
 description: The application method's details.
-x-schemaName: AdminCreateApplicationMethod
+x-schemaName: AdminApplicationMethod
 required:
-  - value
+  - id
-  - type
-  - target_type
 properties:
-  description:
+  promotion:
+    $ref: ./AdminPromotion.yaml
+  target_rules:
+    type: array
+    description: The application method's target rules.
+    items:
+      $ref: ./AdminPromotionRule.yaml
+  buy_rules:
+    type: array
+    description: The application method's buy rules.
+    items:
+      $ref: ./AdminPromotionRule.yaml
+  id:
     type: string
-    title: description
+    title: id
-    description: The application method's description.
+    description: The application method's ID.
-  value:
-    type: number
-    title: value
-    description: >-
-      The discounted amount applied by the associated promotion based on the
-      `type`.
-  currency_code:
-    type: string
-    title: currency_code
-    description: The application method's currency code.
-  max_quantity:
-    type: number
-    title: max_quantity
-    description: >-
-      The max quantity allowed in the cart for the associated promotion to be
-      applied.
   type:
     type: string
     description: >-
-      The type of the application method indicating how the associated promotion
+      The application method's type. If it's `fixed`, the promotion discounts a
-      is applied.
+      fixed amount. If it's `percentage`, the promotion discounts a percentage.
     enum:
       - fixed
       - percentage
   target_type:
     type: string
     description: >-
-      The target type of the application method indicating whether the
+      Which item does the promotion apply to. `items` mean the promotion applies
-      associated promotion is applied to the cart's items, shipping methods, or
+      to the cart's items; `shipping_methods` means the promotion applies to the
-      the whole order.
+      cart's shipping methods; `order` means the promotion applies on the entire
+      order.
     enum:
       - items
       - shipping_methods
@@ -47,28 +42,27 @@ properties:
   allocation:
     type: string
     description: >-
-      The allocation value that indicates whether the associated promotion is
+      How is the promotion amount discounted. `each` means the discounted amount
-      applied on each item in a cart or split between the items in the cart.
+      is applied on each applicable item; `across` means the discounted amount
+      is split accross the applicable items.
     enum:
       - each
       - across
-  target_rules:
+  value:
-    type: array
-    description: The application method's target rules.
-    items:
-      $ref: ./AdminCreatePromotionRule.yaml
-  buy_rules:
-    type: array
-    description: The application method's buy rules.
-    items:
-      $ref: ./AdminCreatePromotionRule.yaml
-  apply_to_quantity:
     type: number
-    title: apply_to_quantity
+    title: value
+    description: The amount to be discounted.
+  currency_code:
+    type: string
+    title: currency_code
+    description: The application method's currency code.
+    example: usd
+  max_quantity:
+    type: number
+    title: max_quantity
     description: >-
-      The quantity that results from matching the `buyget` promotion's
+      The max quantity allowed in the cart for the associated promotion to be
-      condition. For example, if the promotion is a "Buy 2 shirts get 1 free",
+      applied.
-      the value f this attribute is `1`.
   buy_rules_min_quantity:
     type: number
     title: buy_rules_min_quantity
@@ -76,3 +70,10 @@ properties:
       The minimum quantity required for a `buyget` promotion to be applied. For
       example, if the promotion is a "Buy 2 shirts get 1 free", the value of
       this attribute is `2`.
+  apply_to_quantity:
+    type: number
+    title: apply_to_quantity
+    description: >-
+      The quantity that results from matching the `buyget` promotion's
+      condition. For example, if the promotion is a "Buy 2 shirts get 1 free",
+      the value of this attribute is `1`.

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

@@ -1,10 +0,0 @@
-type: object
-description: SUMMARY
-x-schemaName: AdminArchiveOrder
-required:
-  - order_id
-properties:
-  order_id:
-    type: string
-    title: order_id
-    description: The order's order id.

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

@@ -2,44 +2,18 @@ type: object
 description: The claim's details.
 x-schemaName: AdminClaim
 required:
-  - order_id
+  - order
-  - claim_items
+  - return
-  - additional_items
-  - currency_code
   - id
-  - region_id
+  - type
-  - customer_id
+  - order_id
-  - sales_channel_id
+  - display_id
-  - email
+  - order_version
-  - shipping_methods
-  - payment_status
-  - fulfillment_status
-  - summary
-  - metadata
   - created_at
   - updated_at
-  - original_item_total
+  - canceled_at
-  - original_item_subtotal
+  - additional_items
-  - original_item_tax_total
+  - claim_items
-  - item_total
-  - item_subtotal
-  - item_tax_total
-  - original_total
-  - original_subtotal
-  - original_tax_total
-  - total
-  - subtotal
-  - tax_total
-  - discount_total
-  - discount_tax_total
-  - gift_card_total
-  - gift_card_tax_total
-  - shipping_total
-  - shipping_subtotal
-  - shipping_tax_total
-  - original_shipping_total
-  - original_shipping_subtotal
-  - original_shipping_tax_total
 properties:
   id:
     type: string
@@ -60,7 +34,7 @@ properties:
     items:
       $ref: ./BaseClaimItem.yaml
   return:
-    $ref: ./Return.yaml
+    $ref: ./AdminReturn.yaml
   return_id:
     type: string
     title: return_id
@@ -73,76 +47,15 @@ properties:
     type: number
     title: refund_amount
     description: The amount to be refunded.
-  currency_code:
-    type: string
-    title: currency_code
-    description: The claim's currency code.
-  region_id:
-    type: string
-    title: region_id
-    description: The ID of the region associated with the claim.
-  customer_id:
-    type: string
-    title: customer_id
-    description: The ID of the customer associated with the claim's order.
-  sales_channel_id:
-    type: string
-    title: sales_channel_id
-    description: The ID of the sales channel the claim's order is created in.
-  email:
-    type: string
-    title: email
-    description: The email associated with the claim's order.
-    format: email
   display_id:
     type: number
     title: display_id
     description: The claim's display ID.
-  shipping_address:
-    $ref: ./BaseOrderAddress.yaml
-  billing_address:
-    $ref: ./BaseOrderAddress.yaml
   shipping_methods:
     type: array
     description: The claim's shipping methods.
     items:
-      $ref: ./BaseOrderShippingMethod.yaml
+      $ref: ./AdminOrderShippingMethod.yaml
-  payment_collections:
-    type: array
-    description: The claim's payment collections.
-    items:
-      $ref: ./BasePaymentCollection.yaml
-  payment_status:
-    type: string
-    description: The claim's payment status.
-    enum:
-      - canceled
-      - not_paid
-      - awaiting
-      - authorized
-      - partially_authorized
-      - captured
-      - partially_captured
-      - partially_refunded
-      - refunded
-      - requires_action
-  fulfillments:
-    type: array
-    description: The claim's fulfillments.
-    items:
-      $ref: ./BaseOrderFulfillment.yaml
-  fulfillment_status:
-    type: string
-    description: The claim's fulfillment status.
-    enum:
-      - canceled
-      - not_fulfilled
-      - partially_fulfilled
-      - fulfilled
-      - partially_shipped
-      - shipped
-      - partially_delivered
-      - delivered
   transactions:
     type: array
     description: The claim's transactions.
@@ -152,8 +65,6 @@ properties:
       description: Learn more about transactions of orders and associated models.
     items:
       $ref: ./BaseOrderTransaction.yaml
-  summary:
-    $ref: ./BaseOrderSummary.yaml
   metadata:
     type: object
     description: The claim's metadata, used to store custom key-value pairs.
@@ -167,91 +78,29 @@ properties:
     format: date-time
     title: updated_at
     description: The claim's update date.
-  original_item_total:
+  order:
-    type: number
+    $ref: ./AdminOrder.yaml
-    title: original_item_total
+  type:
-    description: The total of the original items in the associated order.
+    type: string
-  original_item_subtotal:
+    description: The claim's type.
-    type: number
+    enum:
-    title: original_item_subtotal
+      - replace
-    description: The subtotal of the original items in the associated order.
+      - refund
-  original_item_tax_total:
+  order_version:
-    type: number
+    type: string
-    title: original_item_tax_total
+    title: order_version
-    description: The tax total of the original items in the associated order.
+    description: The version of the order when the claim is applied.
-  item_total:
+  created_by:
-    type: number
+    type: string
-    title: item_total
+    title: created_by
-    description: The total of the claim's items.
+    description: The ID of the user that created the claim.
-  item_subtotal:
+  canceled_at:
-    type: number
+    type: string
-    title: item_subtotal
+    title: canceled_at
-    description: The subtotal of the claim's items.
+    description: The date the claim was canceled.
-  item_tax_total:
+    format: date-time
-    type: number
+  deleted_at:
-    title: item_tax_total
+    type: string
-    description: The tax total of the claim's items.
+    format: date-time
-  original_total:
+    title: deleted_at
-    type: number
+    description: The date the claim was deleted.
-    title: original_total
-    description: The associated order's original total.
-  original_subtotal:
-    type: number
-    title: original_subtotal
-    description: The associated order's original subtotal.
-  original_tax_total:
-    type: number
-    title: original_tax_total
-    description: The associated order's original tax total.
-  total:
-    type: number
-    title: total
-    description: The associated order's total.
-  subtotal:
-    type: number
-    title: subtotal
-    description: The claim's subtotal.
-  tax_total:
-    type: number
-    title: tax_total
-    description: The claim's tax total.
-  discount_total:
-    type: number
-    title: discount_total
-    description: The claim's discount total.
-  discount_tax_total:
-    type: number
-    title: discount_tax_total
-    description: The claim's discount tax total.
-  gift_card_total:
-    type: number
-    title: gift_card_total
-    description: The claim's gift card total.
-  gift_card_tax_total:
-    type: number
-    title: gift_card_tax_total
-    description: The claim's gift card tax total.
-  shipping_total:
-    type: number
-    title: shipping_total
-    description: The claim's shipping total.
-  shipping_subtotal:
-    type: number
-    title: shipping_subtotal
-    description: The claim's shipping subtotal.
-  shipping_tax_total:
-    type: number
-    title: shipping_tax_total
-    description: The claim's shipping tax total.
-  original_shipping_total:
-    type: number
-    title: original_shipping_total
-    description: The associated order's original shipping total.
-  original_shipping_subtotal:
-    type: number
-    title: original_shipping_subtotal
-    description: The associated order's original shipping subtotal.
-  original_shipping_tax_total:
-    type: number
-    title: original_shipping_tax_total
-    description: The associated order's original shipping tax total.

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

@@ -8,6 +8,6 @@ required:
   - claim
 properties:
   order_preview:
-    $ref: ./OrderPreview.yaml
+    $ref: ./AdminOrderPreview.yaml
   claim:
     $ref: ./AdminClaim.yaml

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

@@ -11,6 +11,6 @@ properties:
   return:
     $ref: ./AdminReturn.yaml
   order_preview:
-    $ref: ./OrderPreview.yaml
+    $ref: ./AdminOrderPreview.yaml
   claim:
     $ref: ./AdminClaim.yaml

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

@@ -8,6 +8,6 @@ required:
   - return
 properties:
   order_preview:
-    $ref: ./OrderPreview.yaml
+    $ref: ./AdminOrderPreview.yaml
   return:
     $ref: ./AdminReturn.yaml

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

@@ -2,15 +2,14 @@ type: object
 description: The filfillment's details.
 x-schemaName: AdminCreateFulfillment
 required:
+  - data
+  - order_id
+  - metadata
+  - items
   - location_id
   - provider_id
   - delivery_address
-  - items
   - labels
-  - order
-  - order_id
-  - data
-  - metadata
 properties:
   location_id:
     type: string
@@ -75,8 +74,8 @@ properties:
       description: An item to fulfill.
       required:
         - title
-        - sku
         - quantity
+        - sku
         - barcode
       properties:
         title:

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

@@ -48,8 +48,8 @@ properties:
       description: A price's details.
       required:
         - currency_code
-        - amount
         - variant_id
+        - amount
       properties:
         currency_code:
           type: string

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

@@ -0,0 +1,13 @@
+type: object
+description: The details of the product type to create.
+x-schemaName: AdminCreateProductType
+required:
+  - value
+properties:
+  metadata:
+    type: object
+    description: The product's metadata, used to store custom key-value pairs.
+  value:
+    type: string
+    title: value
+    description: The product type's value.

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

@@ -86,3 +86,8 @@ properties:
       the option's value.
     example:
       Color: Black
+  inventory_items:
+    type: array
+    description: The variant's inventory items to create.
+    items:
+      $ref: ./AdminCreateProductVariantInventoryKit.yaml

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

@@ -0,0 +1,20 @@
+type: object
+description: The details of a variant's inventory item.
+x-schemaName: AdminCreateProductVariantInventoryKit
+required:
+  - inventory_item_id
+properties:
+  inventory_item_id:
+    type: string
+    title: inventory_item_id
+    description: The inventory item's ID.
+  required_quantity:
+    type: number
+    title: required_quantity
+    description: >-
+      The number of units a single quantity is equivalent to. For example, if a
+      customer orders one quantity of the variant, Medusa checks the
+      availability of the quantity multiplied by the value set for
+      `required_quantity`. When the customer orders the quantity, Medusa
+      reserves the ordered quantity multiplied by the value set for
+      `required_quantity`.

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

@@ -30,3 +30,10 @@ properties:
     description: The price's rules.
     example:
       region_id: reg_123
+    properties:
+      region_id:
+        type: string
+        title: region_id
+        description: The ID of a region.
+    required:
+      - region_id

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

@@ -13,13 +13,13 @@ properties:
       example, `eq` means that the cart's value for the specified attribute must
       match the specified value.
     enum:
+      - gte
+      - lte
       - gt
       - lt
       - eq
       - ne
       - in
-      - lte
-      - gte
   description:
     type: string
     title: description
@@ -30,7 +30,7 @@ properties:
     description: >-
       The attribute to compare against when checking whether a promotion can be
       applied on a cart.
-    example: item.product.id
+    example: items.product.id
   values:
     oneOf:
       - type: string

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

@@ -1,6 +1,6 @@
 type: object
-description: SUMMARY
+description: The details of the return reason to create.
-x-schemaName: CreateOrderReturnReason
+x-schemaName: AdminCreateReturnReason
 required:
   - value
   - label
@@ -20,7 +20,7 @@ properties:
   parent_return_reason_id:
     type: string
     title: parent_return_reason_id
-    description: The return reason's parent return reason id.
+    description: The ID of the parent return reason.
   metadata:
     type: object
-    description: The return reason's metadata.
+    description: The return reason's metadata, can hold custom key-value pairs.

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

@@ -2,91 +2,19 @@ type: object
 description: The shipping option's details.
 x-schemaName: AdminCreateShippingOption
 required:
-  - name
+  - label
-  - service_zone_id
+  - description
-  - shipping_profile_id
+  - code
-  - price_type
-  - provider_id
-  - type
-  - prices
 properties:
-  name:
+  label:
     type: string
-    title: name
+    title: label
-    description: The shipping option's name.
+    description: The type's label.
-  service_zone_id:
+  description:
     type: string
-    title: service_zone_id
+    title: description
-    description: The ID of the service zone this shipping option belongs to.
+    description: The type's description.
-  shipping_profile_id:
+  code:
     type: string
-    title: shipping_profile_id
+    title: code
-    description: The ID of the shipping profile this shipping option belongs to.
+    description: The type's code.
-  data:
-    type: object
-    description: >-
-      Any data necessary for fulfillment providers to handle shipping methods
-      and fulfillments of this shipping option.
-    externalDocs:
-      url: >-
-        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
-      description: Learn more about the data property.
-  price_type:
-    type: string
-    description: >
-      The shipping option price's type. If `flat`, it means the option has a
-      fixed price set in the `prices` property. `calculated` means that the
-      shipping option's price is calculated during checkout.
-    enum:
-      - flat
-      - calculated
-  provider_id:
-    type: string
-    title: provider_id
-    description: >-
-      The ID of the fulfillment provider used to handle this shipping option and
-      its associated methods and fulfillments.
-  type:
-    type: object
-  prices:
-    type: array
-    description: >-
-      The shipping option's prices. If `price_type` is `calculated`, pass an
-      empty array for this property.
-    items:
-      oneOf:
-        - type: object
-          description: The price for a currency code.
-          x-schemaName: AdminCreateShippingOptionPriceWithCurrency
-          required:
-            - currency_code
-            - amount
-          properties:
-            currency_code:
-              type: string
-              title: currency_code
-              description: The price's currency code.
-            amount:
-              type: number
-              title: amount
-              description: The price's amount.
-        - type: object
-          description: The price in a region.
-          x-schemaName: AdminCreateShippingOptionPriceWithRegion
-          required:
-            - region_id
-            - amount
-          properties:
-            region_id:
-              type: string
-              title: region_id
-              description: The ID of the region this price is used in.
-            amount:
-              type: number
-              title: amount
-              description: The price's amount.
-  rules:
-    type: array
-    description: The shipping option's rules.
-    items:
-      $ref: ./AdminCreateShippingOptionRule.yaml

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

@@ -4,6 +4,7 @@ x-schemaName: AdminCreateTaxRate
 required:
   - name
   - tax_region_id
+  - code
 properties:
   name:
     type: string

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

@@ -21,6 +21,7 @@ properties:
     type: object
     description: The tax region's default tax rate.
     required:
+      - code
       - name
     properties:
       rate:

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

@@ -2,8 +2,8 @@ type: object
 description: The details of the variant-inventory item association.
 x-schemaName: AdminCreateVariantInventoryItem
 required:
-  - required_quantity
   - inventory_item_id
+  - required_quantity
 properties:
   required_quantity:
     type: number

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

@@ -8,7 +8,6 @@ required:
   - name
   - decimal_digits
   - rounding
-  - raw_rounding
   - created_at
   - updated_at
   - deleted_at

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

@@ -3,6 +3,7 @@ description: The customer's details.
 x-schemaName: AdminCustomer
 required:
   - has_account
+  - addresses
   - id
   - email
   - default_billing_address_id
@@ -10,7 +11,6 @@ required:
   - company_name
   - first_name
   - last_name
-  - addresses
 properties:
   id:
     type: string
@@ -54,7 +54,7 @@ properties:
     type: array
     description: The customer's addresses.
     items:
-      $ref: ./BaseCustomerAddress.yaml
+      $ref: ./AdminCustomerAddress.yaml
   phone:
     type: string
     title: phone

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

@@ -2,9 +2,9 @@ type: object
 description: The customer group's details.
 x-schemaName: AdminCustomerGroup
 required:
+  - customers
   - id
   - name
-  - customers
   - metadata
   - created_at
   - updated_at
@@ -21,7 +21,7 @@ properties:
     type: array
     description: The customer group's customers.
     items:
-      $ref: ./BaseCustomer.yaml
+      type: object
   metadata:
     type: object
     description: The customer group's metadata, used to store custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The customer group's details.
 x-schemaName: AdminCustomerGroupResponse
 required:
   - customer_group

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The customer's details.
 x-schemaName: AdminCustomerResponse
 required:
   - customer

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

@@ -2,44 +2,14 @@ type: object
 description: The exchange's details.
 x-schemaName: AdminExchange
 required:
-  - order_id
-  - return_items
-  - additional_items
-  - currency_code
   - id
-  - region_id
+  - order_id
-  - customer_id
-  - sales_channel_id
-  - email
-  - shipping_methods
-  - payment_status
-  - fulfillment_status
-  - summary
-  - metadata
   - created_at
   - updated_at
-  - original_item_total
+  - canceled_at
-  - original_item_subtotal
+  - deleted_at
-  - original_item_tax_total
+  - additional_items
-  - item_total
+  - return_items
-  - item_subtotal
-  - item_tax_total
-  - original_total
-  - original_subtotal
-  - original_tax_total
-  - total
-  - subtotal
-  - tax_total
-  - discount_total
-  - discount_tax_total
-  - gift_card_total
-  - gift_card_tax_total
-  - shipping_total
-  - shipping_subtotal
-  - shipping_tax_total
-  - original_shipping_total
-  - original_shipping_subtotal
-  - original_shipping_tax_total
 properties:
   order_id:
     type: string
@@ -67,88 +37,24 @@ properties:
       be refunded. If positive, additional payment is required from the
       customer.
   return:
-    description: the return associated with the exchange.
     $ref: ./AdminReturn.yaml
   return_id:
     type: string
     title: return_id
     description: The ID of the associated exchange.
-  currency_code:
-    type: string
-    title: currency_code
-    description: The exchange's currency code.
   id:
     type: string
     title: id
     description: The exchange's ID.
-  region_id:
-    type: string
-    title: region_id
-    description: The ID of the associated order's region.
-  customer_id:
-    type: string
-    title: customer_id
-    description: The ID of the customer that placed the order.
-  sales_channel_id:
-    type: string
-    title: sales_channel_id
-    description: The ID of the sales channel the associated order belongs to.
-  email:
-    type: string
-    title: email
-    description: The email used when placing the order.
-    format: email
   display_id:
-    type: number
+    type: string
     title: display_id
     description: The exchange's display ID.
-  shipping_address:
-    description: The shipping address to send new items to.
-    $ref: ./BaseOrderAddress.yaml
-  billing_address:
-    description: The customer's billing address.
-    $ref: ./BaseOrderAddress.yaml
   shipping_methods:
     type: array
     description: The shipping methods used to send the new (outbound) items.
     items:
       $ref: ./BaseOrderShippingMethod.yaml
-  payment_collections:
-    type: array
-    description: The exchange's payment collections.
-    items:
-      $ref: ./BasePaymentCollection.yaml
-  payment_status:
-    type: string
-    description: The exchange's payment status.
-    enum:
-      - canceled
-      - not_paid
-      - awaiting
-      - authorized
-      - partially_authorized
-      - captured
-      - partially_captured
-      - partially_refunded
-      - refunded
-      - requires_action
-  fulfillments:
-    type: array
-    description: The exchange's fulfillments of new (outbound) items.
-    items:
-      $ref: ./BaseOrderFulfillment.yaml
-  fulfillment_status:
-    type: string
-    description: The exchange's fulfillment status.
-    enum:
-      - canceled
-      - not_fulfilled
-      - partially_fulfilled
-      - fulfilled
-      - partially_shipped
-      - shipped
-      - partially_delivered
-      - delivered
   transactions:
     type: array
     description: The exchange's transactions.
@@ -157,9 +63,6 @@ properties:
         https://docs.medusajs.com/v2/resources/commerce-modules/order/transactions
     items:
       $ref: ./BaseOrderTransaction.yaml
-  summary:
-    description: The totals summary of the exchange.
-    $ref: ./BaseOrderSummary.yaml
   metadata:
     type: object
     description: The exchange's metadata, can hold custom key-value pairs.
@@ -173,91 +76,29 @@ properties:
     format: date-time
     title: updated_at
     description: The date that the exchange was updated.
-  original_item_total:
+  order_version:
-    type: number
+    type: string
-    title: original_item_total
+    title: order_version
-    description: The total of the original items in the order.
+    description: The version of the order once the exchange is applied.
-  original_item_subtotal:
+  created_by:
-    type: number
+    type: string
-    title: original_item_subtotal
+    title: created_by
-    description: The subtotal of the original items in the order.
+    description: The ID of the user that created the exchange.
-  original_item_tax_total:
+  canceled_at:
-    type: number
+    type: string
-    title: original_item_tax_total
+    title: canceled_at
-    description: The total tax of the original items in the order.
+    description: The date the exchange was canceled.
-  item_total:
+    format: date-time
-    type: number
+  deleted_at:
-    title: item_total
+    type: string
-    description: The total of the exchange's new items.
+    format: date-time
-  item_subtotal:
+    title: deleted_at
-    type: number
+    description: The date the exchange was deleted.
-    title: item_subtotal
+  order:
-    description: The subtotal of the exchange's new items.
+    $ref: ./AdminOrder.yaml
-  item_tax_total:
+  allow_backorder:
-    type: number
+    type: boolean
-    title: item_tax_total
+    title: allow_backorder
-    description: The tax total of the exchange's new items.
+    description: >-
-  original_total:
+      Whether variants that are out-of-stock can still be added as additional or
-    type: number
+      outbound items.
-    title: original_total
-    description: The total of the order.
-  original_subtotal:
-    type: number
-    title: original_subtotal
-    description: The subtotal of the order.
-  original_tax_total:
-    type: number
-    title: original_tax_total
-    description: The tax total of the order.
-  total:
-    type: number
-    title: total
-    description: The total of the exchange.
-  subtotal:
-    type: number
-    title: subtotal
-    description: The subtotal of the exchange.
-  tax_total:
-    type: number
-    title: tax_total
-    description: The tax total of the exchange.
-  discount_total:
-    type: number
-    title: discount_total
-    description: The discount total of the exchange.
-  discount_tax_total:
-    type: number
-    title: discount_tax_total
-    description: The total taxes on discount of the exchange.
-  gift_card_total:
-    type: number
-    title: gift_card_total
-    description: The gift cards total of the exchange.
-  gift_card_tax_total:
-    type: number
-    title: gift_card_tax_total
-    description: The total taxes on the gift card of the exchange.
-  shipping_total:
-    type: number
-    title: shipping_total
-    description: The exchange's shipping total.
-  shipping_subtotal:
-    type: number
-    title: shipping_subtotal
-    description: The exchange's shipping subtotal.
-  shipping_tax_total:
-    type: number
-    title: shipping_tax_total
-    description: The exchange's shipping tax total.
-  original_shipping_total:
-    type: number
-    title: original_shipping_total
-    description: The order's shipping total.
-  original_shipping_subtotal:
-    type: number
-    title: original_shipping_subtotal
-    description: The order's shipping subtotal.
-  original_shipping_tax_total:
-    type: number
-    title: original_shipping_tax_total
-    description: The order's shipping tax total.

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

@@ -6,6 +6,6 @@ required:
   - exchange
 properties:
   order_preview:
-    $ref: ./OrderPreview.yaml
+    $ref: ./AdminOrderPreview.yaml
   exchange:
     $ref: ./AdminExchange.yaml

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

@@ -7,10 +7,8 @@ required:
   - exchange
 properties:
   return:
-    description: The associated return's details.
     $ref: ./AdminReturn.yaml
   order_preview:
-    description: A preview of the order once the exchange is applied.
+    $ref: ./AdminOrderPreview.yaml
-    $ref: ./OrderPreview.yaml
   exchange:
     $ref: ./AdminExchange.yaml

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

@@ -6,6 +6,6 @@ required:
   - return
 properties:
   order_preview:
-    $ref: ./OrderPreview.yaml
+    $ref: ./AdminOrderPreview.yaml
   return:
     $ref: ./AdminReturn.yaml

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

@@ -37,10 +37,8 @@ properties:
     title: shipping_option_id
     description: The ID of the shipping option this fulfillment is created for.
   provider:
-    description: The details of the fulfillment provider using to handle this fulfillment.
     $ref: ./AdminFulfillmentProvider.yaml
   delivery_address:
-    description: The address to deliver the item to.
     $ref: ./AdminFulfillmentAddress.yaml
   items:
     type: array

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

@@ -1,3 +1,15 @@
 type: object
-description: The shipping option's provider.
+description: The fulfillment provider's details.
 x-schemaName: AdminFulfillmentProvider
+required:
+  - id
+  - is_enabled
+properties:
+  id:
+    type: string
+    title: id
+    description: The provider's ID.
+  is_enabled:
+    type: boolean
+    title: is_enabled
+    description: The provider's is enabled.

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

@@ -1,5 +1,5 @@
 type: object
-description: The fulfillment set's parent.
+description: The service zone's fulfillment set.
 x-schemaName: AdminFulfillmentSet
 required:
   - id
@@ -14,34 +14,34 @@ properties:
   id:
     type: string
     title: id
-    description: The parent's ID.
+    description: The fulfillment set's ID.
   name:
     type: string
     title: name
-    description: The parent's name.
+    description: The fulfillment set's name.
   type:
     type: string
     title: type
-    description: The parent's type.
+    description: The fulfillment set's type.
   location:
     $ref: ./AdminStockLocation.yaml
   service_zones:
     type: array
-    description: The parent's service zones.
+    description: The fulfillment set's service zones.
     items:
       $ref: ./AdminServiceZone.yaml
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The parent's created at.
+    description: The fulfillment set's created at.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The parent's updated at.
+    description: The fulfillment set's updated at.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The parent's deleted at.
+    description: The fulfillment set's deleted at.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The fulfillment set's details.
 x-schemaName: AdminFulfillmentSetResponse
 required:
   - fulfillment_set

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

@@ -1,5 +1,5 @@
 type: object
-description: The geo zone's details.
+description: The geo zone's geo zones.
 x-schemaName: AdminGeoZone
 required:
   - id
@@ -43,14 +43,14 @@ properties:
     type: string
     format: date-time
     title: created_at
-    description: The date the geo zone was created.
+    description: The geo zone's created at.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The date the geo zone was update.
+    description: The geo zone's updated at.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The date the geo zone was deleted.
+    description: The geo zone's deleted at.

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

@@ -5,4 +5,9 @@ required:
   - file
 properties:
   file:
-    $ref: ./File.yaml
+    type: object
+    description: A File to upload.
+    externalDocs:
+      url: https://developer.mozilla.org/en-US/docs/Web/API/File
+      description: Learn more about the File API
+    title: file

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

@@ -1,5 +1,5 @@
 type: object
-description: The inventory item's details.
+description: The reservation's inventory item.
 x-schemaName: AdminInventoryItem
 required:
   - id
@@ -12,7 +12,7 @@ properties:
   sku:
     type: string
     title: sku
-    description: The inventory item's SKU.
+    description: The inventory item's sku.
   origin_country:
     type: string
     title: origin_country
@@ -20,15 +20,15 @@ properties:
   hs_code:
     type: string
     title: hs_code
-    description: The inventory item's HS code.
+    description: The inventory item's hs code.
   requires_shipping:
     type: boolean
     title: requires_shipping
-    description: Whether the inventory item requires shipping.
+    description: The inventory item's requires shipping.
   mid_code:
     type: string
     title: mid_code
-    description: The inventory item's MID code.
+    description: The inventory item's mid code.
   material:
     type: string
     title: material
@@ -60,12 +60,12 @@ properties:
   thumbnail:
     type: string
     title: thumbnail
-    description: The URL of the inventory item's thumbnail.
+    description: The inventory item's thumbnail.
   metadata:
     type: object
-    description: The inventory item's metadata, can hold custom key-value pairs.
+    description: The inventory item's metadata.
   location_levels:
     type: array
-    description: The inventory item's associated inventory levels.
+    description: The inventory item's location levels.
     items:
       $ref: ./AdminInventoryLevel.yaml

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

@@ -1,5 +1,5 @@
 type: object
-description: The inventory level's details.
+description: The location level's location levels.
 x-schemaName: AdminInventoryLevel
 required:
   - id
@@ -9,67 +9,56 @@ required:
   - inventory_item_id
   - location_id
   - stocked_quantity
-  - raw_stocked_quantity
   - reserved_quantity
-  - raw_reserved_quantity
   - incoming_quantity
-  - raw_incoming_quantity
   - metadata
   - available_quantity
 properties:
   id:
     type: string
     title: id
-    description: The inventory level's ID.
+    description: The location level's ID.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The location level's created at.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The location level's updated at.
+  deleted_at:
+    type: string
+    format: date-time
+    title: deleted_at
+    description: The location level's deleted at.
   inventory_item_id:
     type: string
     title: inventory_item_id
-    description: The ID of the inventory item this level belongs to.
+    description: The location level's inventory item id.
   location_id:
     type: string
     title: location_id
-    description: The ID of the stock location this level belongs to.
+    description: The location level's location id.
   stocked_quantity:
     type: number
     title: stocked_quantity
-    description: >-
+    description: The location level's stocked quantity.
-      The quantity of the associated inventory item stocked in the associated
-      stock location.
   reserved_quantity:
     type: number
     title: reserved_quantity
-    description: >-
+    description: The location level's reserved quantity.
-      The reserved quantity of the associated inventory item stocked in the
-      associated stock location.
   incoming_quantity:
     type: number
     title: incoming_quantity
-    description: >-
+    description: The location level's incoming quantity.
-      The incoming quantity of the associated inventory item stocked in the
-      associated stock location.
   metadata:
     type: object
-    description: The location level's metadata, can hold custom key-value pairs.
+    description: The location level's metadata.
   inventory_item:
     type: object
   available_quantity:
     type: number
     title: available_quantity
-    description: >-
+    description: The location level's available quantity.
-      The quantity available for order of the associated inventory item in the
-      associated stock location.
-  created_at:
-    type: string
-    format: date-time
-    title: created_at
-    description: The date the inventory level was created.
-  updated_at:
-    type: string
-    format: date-time
-    title: updated_at
-    description: The date the inventory level was updated.
-  deleted_at:
-    type: string
-    format: date-time
-    title: deleted_at
-    description: The date the inventory level was deleted.

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

@@ -3,21 +3,20 @@ description: The order's details.
 x-schemaName: AdminOrder
 required:
   - payment_collections
+  - items
+  - shipping_methods
+  - currency_code
   - id
+  - created_at
+  - updated_at
+  - email
   - version
   - region_id
   - customer_id
   - sales_channel_id
-  - email
-  - currency_code
-  - items
-  - shipping_methods
   - payment_status
   - fulfillment_status
   - summary
-  - metadata
-  - created_at
-  - updated_at
   - original_item_total
   - original_item_subtotal
   - original_item_tax_total
@@ -50,7 +49,7 @@ properties:
     type: array
     description: The order's fulfillments.
     items:
-      $ref: ./BaseOrderFulfillment.yaml
+      $ref: ./AdminOrderFulfillment.yaml
   sales_channel:
     $ref: ./AdminSalesChannel.yaml
   customer:
@@ -96,12 +95,12 @@ properties:
     type: array
     description: The order's items.
     items:
-      $ref: ./BaseOrderLineItem.yaml
+      $ref: ./AdminOrderLineItem.yaml
   shipping_methods:
     type: array
     description: The order's shipping methods.
     items:
-      $ref: ./BaseOrderShippingMethod.yaml
+      $ref: ./AdminOrderShippingMethod.yaml
   payment_status:
     type: string
     description: The order's payment status.

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

@@ -0,0 +1,142 @@
+type: object
+description: The order change's details.
+x-schemaName: AdminOrderChange
+required:
+  - order
+  - claim
+  - return_order
+  - exchange
+  - actions
+  - status
+  - order_id
+  - metadata
+  - id
+  - created_at
+  - updated_at
+  - version
+  - canceled_at
+  - return_id
+  - exchange_id
+  - claim_id
+  - requested_by
+  - requested_at
+  - confirmed_by
+  - confirmed_at
+  - declined_by
+  - declined_reason
+  - declined_at
+  - canceled_by
+properties:
+  id:
+    type: string
+    title: id
+    description: The order change's ID.
+  version:
+    type: number
+    title: version
+    description: >-
+      The order change's version. This will be the order's version when the
+      change is applied.
+  change_type:
+    type: string
+    description: The order change's type.
+    enum:
+      - return
+      - exchange
+      - claim
+      - edit
+  order_id:
+    type: string
+    title: order_id
+    description: The ID of the order this change applies on.
+  return_id:
+    type: string
+    title: return_id
+    description: The ID of the associated return.
+  exchange_id:
+    type: string
+    title: exchange_id
+    description: The ID of the associated exchange.
+  claim_id:
+    type: string
+    title: claim_id
+    description: The ID of the associated claim.
+  order:
+    type: string
+    title: order
+    description: The order change's order.
+    externalDocs:
+      url: '#pagination'
+  return_order:
+    $ref: ./AdminReturn.yaml
+  exchange:
+    $ref: ./AdminExchange.yaml
+  claim:
+    $ref: ./AdminClaim.yaml
+  actions:
+    type: array
+    description: The order change's actions.
+    items:
+      $ref: ./AdminOrderChangeAction.yaml
+  status:
+    type: string
+    description: The order change's status.
+    enum:
+      - canceled
+      - requested
+      - pending
+      - confirmed
+      - declined
+  requested_by:
+    type: string
+    title: requested_by
+    description: The ID of the user that requested the change.
+  requested_at:
+    type: string
+    title: requested_at
+    description: The date the order change was requested.
+    format: date-time
+  confirmed_by:
+    type: string
+    title: confirmed_by
+    description: The ID of the user that confirmed the order change.
+  confirmed_at:
+    type: string
+    title: confirmed_at
+    description: The date the order change was confirmed.
+    format: date-time
+  declined_by:
+    type: string
+    title: declined_by
+    description: The ID of the user that declined the order change.
+  declined_reason:
+    type: string
+    title: declined_reason
+    description: The reason the order change was declined.
+  metadata:
+    type: object
+    description: The order change's metadata, can hold custom key-value pairs.
+  declined_at:
+    type: string
+    title: declined_at
+    description: The date the order change was declined.
+    format: date-time
+  canceled_by:
+    type: string
+    title: canceled_by
+    description: The ID of the user that canceled the order change.
+  canceled_at:
+    type: string
+    title: canceled_at
+    description: The date the order change was canceled.
+    format: date-time
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the order change was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the order change was updated.

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

@@ -0,0 +1,104 @@
+type: object
+description: The order change action's details.
+x-schemaName: AdminOrderChangeAction
+required:
+  - order_change
+  - order
+  - order_id
+  - internal_note
+  - id
+  - created_at
+  - updated_at
+  - return_id
+  - exchange_id
+  - claim_id
+  - order_change_id
+  - reference
+  - reference_id
+  - action
+  - details
+properties:
+  id:
+    type: string
+    title: id
+    description: The action's ID.
+  order_change_id:
+    type: string
+    title: order_change_id
+    description: The ID of the order change that the action belongs to.
+  order_change:
+    type: object
+  order_id:
+    type: string
+    title: order_id
+    description: The ID of the order the associated change is for.
+  return_id:
+    type: string
+    title: return_id
+    description: The ID of the associated return.
+  claim_id:
+    type: string
+    title: claim_id
+    description: The ID of the associated claim.
+  exchange_id:
+    type: string
+    title: exchange_id
+    description: The ID of the associated exchange.
+  order:
+    type: string
+    title: order
+    description: The order change's order.
+    externalDocs:
+      url: '#pagination'
+  reference:
+    type: string
+    title: reference
+    description: The name of the table this action applies on.
+    enum:
+      - claim
+      - exchange
+      - return
+      - order_shipping_method
+  reference_id:
+    type: string
+    title: reference_id
+    description: The ID of the record in the referenced table.
+  action:
+    type: string
+    description: The applied action.
+    enum:
+      - CANCEL_RETURN_ITEM
+      - FULFILL_ITEM
+      - DELIVER_ITEM
+      - CANCEL_ITEM_FULFILLMENT
+      - ITEM_ADD
+      - ITEM_REMOVE
+      - ITEM_UPDATE
+      - RECEIVE_DAMAGED_RETURN_ITEM
+      - RECEIVE_RETURN_ITEM
+      - RETURN_ITEM
+      - SHIPPING_ADD
+      - SHIPPING_REMOVE
+      - SHIP_ITEM
+      - WRITE_OFF_ITEM
+      - REINSTATE_ITEM
+  details:
+    type: object
+    description: The action's details.
+    example:
+      reference_id: 123
+      quantity: 1
+  internal_note:
+    type: string
+    title: internal_note
+    description: A note that's viewed only by admin users.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the action was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the action was updated.

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

@@ -8,4 +8,4 @@ properties:
     type: array
     description: An order's changes.
     items:
-      $ref: ./BaseOrderChange.yaml
+      $ref: ./AdminOrderChange.yaml

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

@@ -5,4 +5,4 @@ required:
   - order_preview
 properties:
   order_preview:
-    $ref: ./OrderPreview.yaml
+    $ref: ./AdminOrderPreview.yaml

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

@@ -5,4 +5,4 @@ required:
   - order_change
 properties:
   order_change:
-    $ref: ./OrderChange.yaml
+    $ref: ./AdminOrderChange.yaml

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

@@ -0,0 +1,79 @@
+type: object
+description: The fulfillment's details.
+x-schemaName: AdminOrderFulfillment
+required:
+  - id
+  - location_id
+  - packed_at
+  - shipped_at
+  - delivered_at
+  - canceled_at
+  - requires_shipping
+  - data
+  - provider_id
+  - shipping_option_id
+  - metadata
+  - created_at
+  - updated_at
+properties:
+  id:
+    type: string
+    title: id
+    description: The fulfillment's ID.
+  location_id:
+    type: string
+    title: location_id
+    description: The ID of the location the items are fulfilled from.
+  packed_at:
+    type: string
+    title: packed_at
+    description: The date the items were packed.
+    format: date-time
+  shipped_at:
+    type: string
+    title: shipped_at
+    description: The date the items were shipped.
+    format: date-time
+  delivered_at:
+    type: string
+    title: delivered_at
+    description: The date the items were delivered.
+    format: date-time
+  canceled_at:
+    type: string
+    title: canceled_at
+    description: The date the items were canceled.
+    format: date-time
+  data:
+    type: object
+    description: >-
+      Data useful for the fulfillment provider handling it. This is taken from
+      the associated shipping option.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
+  provider_id:
+    type: string
+    title: provider_id
+    description: The ID of the fulfillment provider used to handle the fulfillment.
+  shipping_option_id:
+    type: string
+    title: shipping_option_id
+    description: The ID of the associated shipping option.
+  metadata:
+    type: object
+    description: The fulfillment's metadata, can hold custom key-value pairs.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the fulfillment was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the fulfillment was updated.
+  requires_shipping:
+    type: boolean
+    title: requires_shipping
+    description: Whether the fulfillment requires shipping.

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

@@ -0,0 +1,213 @@
+type: object
+description: The item's details.
+x-schemaName: AdminOrderLineItem
+required:
+  - title
+  - metadata
+  - id
+  - subtitle
+  - thumbnail
+  - created_at
+  - updated_at
+  - item_total
+  - item_subtotal
+  - item_tax_total
+  - original_total
+  - original_subtotal
+  - original_tax_total
+  - total
+  - subtotal
+  - tax_total
+  - discount_total
+  - discount_tax_total
+  - variant_id
+  - product_id
+  - product_title
+  - product_description
+  - product_subtitle
+  - product_type
+  - product_collection
+  - product_handle
+  - variant_sku
+  - variant_barcode
+  - variant_title
+  - variant_option_values
+  - requires_shipping
+  - is_discountable
+  - is_tax_inclusive
+  - unit_price
+  - quantity
+  - detail
+  - refundable_total
+  - refundable_total_per_unit
+properties:
+  id:
+    type: string
+    title: id
+    description: The item's ID.
+  title:
+    type: string
+    title: title
+    description: The item's title.
+  subtitle:
+    type: string
+    title: subtitle
+    description: The item's subtitle.
+  thumbnail:
+    type: string
+    title: thumbnail
+    description: The URL of the item's thumbnail.
+  variant:
+    $ref: ./AdminProductVariant.yaml
+  variant_id:
+    type: string
+    title: variant_id
+    description: The ID of the associated variant.
+  product:
+    $ref: ./AdminProduct.yaml
+  product_id:
+    type: string
+    title: product_id
+    description: The ID of the associated product.
+  product_title:
+    type: string
+    title: product_title
+    description: The item's product title.
+  product_description:
+    type: string
+    title: product_description
+    description: The item's product description.
+  product_subtitle:
+    type: string
+    title: product_subtitle
+    description: The item's product subtitle.
+  product_type:
+    type: string
+    title: product_type
+    description: The item's product type.
+  product_collection:
+    type: string
+    title: product_collection
+    description: The ID of the collection the item's product belongs to.
+  product_handle:
+    type: string
+    title: product_handle
+    description: The item's product handle.
+  variant_sku:
+    type: string
+    title: variant_sku
+    description: The item's variant SKU.
+  variant_barcode:
+    type: string
+    title: variant_barcode
+    description: The item's variant barcode.
+  variant_title:
+    type: string
+    title: variant_title
+    description: The item's variant title.
+  variant_option_values:
+    type: object
+    description: The values of the item variant's options.
+    example:
+      Color: Blue
+  requires_shipping:
+    type: boolean
+    title: requires_shipping
+    description: Whether the item requires shipping.
+  is_discountable:
+    type: boolean
+    title: is_discountable
+    description: Whether the item is discountable.
+  is_tax_inclusive:
+    type: boolean
+    title: is_tax_inclusive
+    description: Whether the item is tax inclusive.
+  compare_at_unit_price:
+    type: number
+    title: compare_at_unit_price
+    description: The original price of the item before a promotion or sale.
+  unit_price:
+    type: number
+    title: unit_price
+    description: The item's unit price.
+  quantity:
+    type: number
+    title: quantity
+    description: The item's quantity.
+  tax_lines:
+    type: array
+    description: The item's tax lines.
+    items:
+      $ref: ./BaseOrderLineItemTaxLine.yaml
+  adjustments:
+    type: array
+    description: The item's adjustments.
+    items:
+      $ref: ./BaseOrderLineItemAdjustment.yaml
+  detail:
+    type: object
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the item was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the item was updated.
+  metadata:
+    type: object
+    description: The item's metadata, can hold custom key-value pairs.
+  original_total:
+    type: number
+    title: original_total
+    description: The item's total including taxes, excluding promotions.
+  original_subtotal:
+    type: number
+    title: original_subtotal
+    description: The item's total excluding taxes, including promotions.
+  original_tax_total:
+    type: number
+    title: original_tax_total
+    description: The total taxes of the item, excluding promotions.
+  item_total:
+    type: number
+    title: item_total
+    description: The total taxes of the item, including promotions.
+  item_subtotal:
+    type: number
+    title: item_subtotal
+    description: The item's total excluding taxes, including promotions.
+  item_tax_total:
+    type: number
+    title: item_tax_total
+    description: The total taxes of the item, including promotions.
+  total:
+    type: number
+    title: total
+    description: The item's total, including taxes and promotions.
+  subtotal:
+    type: number
+    title: subtotal
+    description: The item's subtotal excluding taxes, including promotions.
+  tax_total:
+    type: number
+    title: tax_total
+    description: The tax total of the item including promotions.
+  discount_total:
+    type: number
+    title: discount_total
+    description: The total discount amount of the item.
+  discount_tax_total:
+    type: number
+    title: discount_tax_total
+    description: The total taxes applied on the discounted amount.
+  refundable_total:
+    type: number
+    title: refundable_total
+    description: The total refundable amount of the item's total.
+  refundable_total_per_unit:
+    type: number
+    title: refundable_total_per_unit
+    description: The total refundable amount of the item's total for a single quantity.

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

@@ -7,19 +7,18 @@ required:
   - return_requested_total
   - order_change
   - currency_code
-  - version
   - id
+  - created_at
+  - updated_at
+  - email
+  - version
   - region_id
   - customer_id
   - sales_channel_id
-  - email
   - payment_collections
   - payment_status
   - fulfillment_status
   - summary
-  - metadata
-  - created_at
-  - updated_at
   - original_item_total
   - original_item_subtotal
   - original_item_tax_total
@@ -48,7 +47,7 @@ properties:
     title: return_requested_total
     description: The total of the requested return.
   order_change:
-    $ref: ./BaseOrderChange.yaml
+    $ref: ./AdminOrderChange.yaml
   items:
     type: array
     description: The order's items.
@@ -120,7 +119,7 @@ properties:
               title: variant_id
               description: The ID of the associated variant.
             product:
-              $ref: ./BaseProduct.yaml
+              $ref: ./AdminProduct.yaml
             product_id:
               type: string
               title: product_id
@@ -181,8 +180,8 @@ properties:
               description: Whether the item's price includes taxes.
             compare_at_unit_price:
               type: number
-              title: The original price of the item before a promotion or sale.
+              title: compare_at_unit_price
-              description: The
+              description: The original price of the item before a promotion or sale.
             unit_price:
               type: number
               title: unit_price
@@ -519,7 +518,7 @@ properties:
     type: array
     description: The order's fulfillments.
     items:
-      $ref: ./BaseOrderFulfillment.yaml
+      $ref: ./AdminOrderFulfillment.yaml
   fulfillment_status:
     type: string
     description: The order's fulfillment status.

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

@@ -0,0 +1,116 @@
+type: object
+description: The shipping method's details.
+x-schemaName: AdminOrderShippingMethod
+required:
+  - id
+  - order_id
+  - name
+  - amount
+  - is_tax_inclusive
+  - shipping_option_id
+  - data
+  - metadata
+  - original_total
+  - original_subtotal
+  - original_tax_total
+  - total
+  - subtotal
+  - tax_total
+  - discount_total
+  - discount_tax_total
+  - created_at
+  - updated_at
+properties:
+  id:
+    type: string
+    title: id
+    description: The shipping method's ID.
+  order_id:
+    type: string
+    title: order_id
+    description: The ID of the order the shipping method belongs to.
+  name:
+    type: string
+    title: name
+    description: The shipping method's name.
+  description:
+    type: string
+    title: description
+    description: The shipping method's description.
+  amount:
+    type: number
+    title: amount
+    description: The shipping method's amount.
+  is_tax_inclusive:
+    type: boolean
+    title: is_tax_inclusive
+    description: Whether the shipping method's amount includes applied taxes.
+  shipping_option_id:
+    type: string
+    title: shipping_option_id
+    description: The ID of the shipping option this method was created from.
+  data:
+    type: object
+    description: >-
+      The shipping method's data, useful for fulfillment provider handling its
+      fulfillment.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
+  metadata:
+    type: object
+    description: The shipping method's metadata, can hold custom key-value pairs.
+  tax_lines:
+    type: array
+    description: The shipping method's tax lines.
+    items:
+      $ref: ./BaseOrderShippingMethodTaxLine.yaml
+  adjustments:
+    type: array
+    description: The shipping method's adjustments.
+    items:
+      $ref: ./BaseOrderShippingMethodAdjustment.yaml
+  original_total:
+    type: number
+    title: original_total
+    description: The shipping method's total including taxes, excluding promotions.
+  original_subtotal:
+    type: number
+    title: 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 total taxes excluding promotions.
+  total:
+    type: number
+    title: total
+    description: The shipping method's total including taxes and promotions.
+  subtotal:
+    type: number
+    title: subtotal
+    description: The shipping method's total excluding taxes, including promotions.
+  tax_total:
+    type: number
+    title: tax_total
+    description: The shipping method's tax total including promotions.
+  discount_total:
+    type: number
+    title: discount_total
+    description: The total discounts applied on the shipping method.
+  discount_tax_total:
+    type: number
+    title: discount_tax_total
+    description: The taxes applied on the discount amount.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the shipping method was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the shipping method was updated.
+  detail:
+    $ref: ./BaseOrderShippingDetail.yaml

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

@@ -86,8 +86,8 @@ properties:
     type: array
     description: The details of payment refunds.
     items:
-      $ref: ./BaseRefund.yaml
+      $ref: ./AdminRefund.yaml
   payment_collection:
-    $ref: ./BasePaymentCollection.yaml
+    type: object
   payment_session:
-    $ref: ./BasePaymentSession.yaml
+    $ref: ./AdminPaymentSession.yaml

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

@@ -2,12 +2,12 @@ type: object
 description: The payment collection's details.
 x-schemaName: AdminPaymentCollection
 required:
+  - payment_providers
   - id
   - currency_code
   - region_id
   - amount
   - status
-  - payment_providers
 properties:
   id:
     type: string
@@ -70,14 +70,14 @@ properties:
       The payment provider used to process the collection's payments and
       sessions.
     items:
-      $ref: ./BasePaymentProvider.yaml
+      $ref: ./AdminPaymentProvider.yaml
   payment_sessions:
     type: array
     description: The payment collection's payment sessions.
     items:
-      $ref: ./BasePaymentSession.yaml
+      $ref: ./AdminPaymentSession.yaml
   payments:
     type: array
     description: The payment collection's payments.
     items:
-      $ref: ./BasePayment.yaml
+      $ref: ./AdminPayment.yaml

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

@@ -0,0 +1,61 @@
+type: object
+description: The payment session's details.
+x-schemaName: AdminPaymentSession
+properties:
+  id:
+    type: string
+    title: id
+    description: The payment session's ID.
+  amount:
+    type: number
+    title: amount
+    description: The payment session's amount.
+  currency_code:
+    type: string
+    title: currency_code
+    description: The payment session's currency code.
+    example: usd
+  provider_id:
+    type: string
+    title: provider_id
+    description: The ID of the payment provider processing this session.
+  data:
+    type: object
+    description: >-
+      The payment session's data, useful for the payment provider processing the
+      payment.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/v2/resources/commerce-modules/payment/payment-session#data-property
+  context:
+    type: object
+    description: The context around the payment, such as the customer's details.
+    example:
+      customer:
+        id: cus_123
+  status:
+    type: string
+    description: The payment session's status.
+    enum:
+      - authorized
+      - captured
+      - canceled
+      - pending
+      - requires_more
+      - error
+  authorized_at:
+    type: string
+    title: authorized_at
+    description: The date the payment session was authorized.
+    format: date-time
+  payment_collection:
+    type: object
+  payment:
+    $ref: ./BasePayment.yaml
+required:
+  - id
+  - amount
+  - currency_code
+  - provider_id
+  - data
+  - status

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

@@ -2,15 +2,15 @@ type: object
 description: The product's details.
 x-schemaName: AdminProduct
 required:
+  - variants
   - type
+  - options
+  - images
   - length
   - title
   - status
-  - options
   - description
   - id
-  - created_at
-  - updated_at
   - handle
   - subtitle
   - is_giftcard
@@ -24,9 +24,10 @@ required:
   - material
   - collection_id
   - type_id
-  - images
   - discountable
   - external_id
+  - created_at
+  - updated_at
   - deleted_at
 properties:
   collection:
@@ -73,7 +74,7 @@ properties:
     type: array
     description: The product's options.
     items:
-      $ref: ./BaseProductOption.yaml
+      $ref: ./AdminProductOption.yaml
   description:
     type: string
     title: description
@@ -151,7 +152,7 @@ properties:
     type: array
     description: The product's images.
     items:
-      $ref: ./BaseProductImage.yaml
+      $ref: ./AdminProductImage.yaml
   discountable:
     type: boolean
     title: discountable

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

@@ -0,0 +1,33 @@
+type: object
+description: The image's details.
+x-schemaName: AdminProductImage
+properties:
+  id:
+    type: string
+    title: id
+    description: The image's ID.
+  url:
+    type: string
+    title: url
+    description: The image's URL.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the image was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the image was updated.
+  deleted_at:
+    type: string
+    format: date-time
+    title: deleted_at
+    description: The date the image was deleted.
+  metadata:
+    type: object
+    description: The image's metadata, can hold custom key-value pairs.
+required:
+  - id
+  - url

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

@@ -1,5 +1,5 @@
 type: object
-description: The product's product option.
+description: The product option's details.
 x-schemaName: AdminProductOption
 required:
   - id
@@ -14,31 +14,31 @@ properties:
     title: title
     description: The product option's title.
   product:
-    $ref: ./BaseProduct.yaml
+    type: object
   product_id:
     type: string
     title: product_id
-    description: The product option's product id.
+    description: The ID of the product this option belongs to.
   values:
     type: array
     description: The product option's values.
     items:
-      $ref: ./BaseProductOptionValue.yaml
+      type: object
   metadata:
     type: object
-    description: The product option's metadata.
+    description: The product option's metadata, can hold custom key-value pairs.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The product option's created at.
+    description: The date the product option was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The product option's updated at.
+    description: The date the product option was updated.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The product option's deleted at.
+    description: The date the product option was deleted.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product option deletion.
 x-schemaName: AdminProductOptionDeleteResponse
 required:
   - id
@@ -9,14 +9,15 @@ properties:
   id:
     type: string
     title: id
-    description: The product's ID.
+    description: The product option's ID.
   object:
     type: string
     title: object
     description: The name of the deleted object.
+    default: product_option
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Product was deleted.
+    description: Whether the product option was deleted.
   parent:
     $ref: ./AdminProduct.yaml

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product option's details.
 x-schemaName: AdminProductOptionResponse
 required:
   - product_option

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

@@ -0,0 +1,39 @@
+type: object
+description: The product option value's details.
+x-schemaName: AdminProductOptionValue
+required:
+  - id
+  - value
+properties:
+  id:
+    type: string
+    title: id
+    description: The value's ID.
+  value:
+    type: string
+    title: value
+    description: The value.
+  option:
+    $ref: ./AdminProductOption.yaml
+  option_id:
+    type: string
+    title: option_id
+    description: The ID of the option this value belongs to.
+  metadata:
+    type: object
+    description: The value's metadata, can hold custom key-value pairs.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the value was created.
+  updated_at:
+    type: string
+    format: date-time
+    title: updated_at
+    description: The date the value was updated.
+  deleted_at:
+    type: string
+    format: date-time
+    title: deleted_at
+    description: The date the value was deleted.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product's details.
 x-schemaName: AdminProductResponse
 required:
   - product

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

@@ -1,5 +1,5 @@
 type: object
-description: The tag's tags.
+description: The product tag's details.
 x-schemaName: AdminProductTag
 required:
   - id
@@ -19,17 +19,17 @@ properties:
     type: string
     format: date-time
     title: created_at
-    description: The tag's created at.
+    description: The date the tag was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The tag's updated at.
+    description: The date the tag was updated.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The tag's deleted at.
+    description: The date the tag was deleted.
   metadata:
     type: object
-    description: The tag's metadata.
+    description: The tag's metadata, can hold custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product tag deletion.
 x-schemaName: AdminProductTagDeleteResponse
 required:
   - id
@@ -18,4 +18,4 @@ properties:
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Product Tag was deleted.
+    description: Whether the product tag was deleted.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of product tags.
 x-schemaName: AdminProductTagListResponse
 required:
   - limit
@@ -10,17 +10,17 @@ properties:
   limit:
     type: number
     title: limit
-    description: The product tag's limit.
+    description: The maximum number of items returned.
   offset:
     type: number
     title: offset
-    description: The product tag's offset.
+    description: The number of items skipped before retrieving the returned items.
   count:
     type: number
     title: count
-    description: The product tag's count.
+    description: The total number of items.
   product_tags:
     type: array
-    description: The product tag's product tags.
+    description: The list of product tags.
     items:
       $ref: ./AdminProductTag.yaml

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product tag's details.
 x-schemaName: AdminProductTagResponse
 required:
   - product_tag

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

@@ -1,5 +1,5 @@
 type: object
-description: The parent's type.
+description: The product type's details.
 x-schemaName: AdminProductType
 required:
   - id
@@ -19,17 +19,17 @@ properties:
     type: string
     format: date-time
     title: created_at
-    description: The type's created at.
+    description: The date the type was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The type's updated at.
+    description: The date the type was updated.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The type's deleted at.
+    description: The date the type was deleted.
   metadata:
     type: object
-    description: The type's metadata.
+    description: The type's metadata, can hold custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product type deletion.
 x-schemaName: AdminProductTypeDeleteResponse
 required:
   - id
@@ -18,4 +18,4 @@ properties:
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Product Type was deleted.
+    description: Whether the product type was deleted.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of product types.
 x-schemaName: AdminProductTypeListResponse
 required:
   - limit
@@ -10,17 +10,17 @@ properties:
   limit:
     type: number
     title: limit
-    description: The product type's limit.
+    description: The maximum number of items returned.
   offset:
     type: number
     title: offset
-    description: The product type's offset.
+    description: The number of items skipped before retrieving the returned items.
   count:
     type: number
     title: count
-    description: The product type's count.
+    description: The total number of items.
   product_types:
     type: array
-    description: The product type's product types.
+    description: The list of product types.
     items:
       $ref: ./AdminProductType.yaml

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product type's details.
 x-schemaName: AdminProductTypeResponse
 required:
   - product_type

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

@@ -1,8 +1,9 @@
 type: object
-description: The product's parent.
+description: The product variant's details.
 x-schemaName: AdminProductVariant
 required:
   - prices
+  - options
   - id
   - title
   - sku
@@ -19,116 +20,119 @@ required:
   - length
   - height
   - width
-  - options
   - created_at
   - updated_at
   - deleted_at
 properties:
   prices:
     type: array
-    description: The parent's prices.
+    description: The variant's prices.
     items:
       $ref: ./AdminPrice.yaml
   id:
     type: string
     title: id
-    description: The parent's ID.
+    description: The variant's ID.
   title:
     type: string
     title: title
-    description: The parent's title.
+    description: The variant's title.
   sku:
     type: string
     title: sku
-    description: The parent's sku.
+    description: The variant's SKU.
   barcode:
     type: string
     title: barcode
-    description: The parent's barcode.
+    description: The variant's barcode.
   ean:
     type: string
     title: ean
-    description: The parent's ean.
+    description: The variant's EAN code.
   upc:
     type: string
     title: upc
-    description: The parent's upc.
+    description: The variant's UPC.
   allow_backorder:
     type: boolean
     title: allow_backorder
-    description: The parent's allow backorder.
+    description: Whether the variant can be ordered even if it's out of stock.
   manage_inventory:
     type: boolean
     title: manage_inventory
-    description: The parent's manage inventory.
+    description: >-
+      Whether the Medusa application manages the variant's inventory quantity
+      and availablility. If disabled, the variant is always considered in stock.
   inventory_quantity:
     type: number
     title: inventory_quantity
-    description: The parent's inventory quantity.
+    description: >-
+      The variant's inventory quantity. This is only included if you pass in the
+      `fields` query parameter a `+variants.inventory_quantity` parameter.
   hs_code:
     type: string
     title: hs_code
-    description: The parent's hs code.
+    description: The variant's HS code.
   origin_country:
     type: string
     title: origin_country
-    description: The parent's origin country.
+    description: The variant's origin country.
   mid_code:
     type: string
     title: mid_code
-    description: The parent's mid code.
+    description: The variant's MID code.
   material:
     type: string
     title: material
-    description: The parent's material.
+    description: The variant's material.
   weight:
     type: number
     title: weight
-    description: The parent's weight.
+    description: The variant's weight.
   length:
     type: number
     title: length
-    description: The parent's length.
+    description: The variant's length.
   height:
     type: number
     title: height
-    description: The parent's height.
+    description: The variant's height.
   width:
     type: number
     title: width
-    description: The parent's width.
+    description: The variant's width.
   variant_rank:
     type: number
     title: variant_rank
-    description: The parent's variant rank.
+    description: The variant's rank among its sibling variants.
   options:
     type: array
-    description: The parent's options.
+    description: The variant's option values.
     items:
-      $ref: ./BaseProductOptionValue.yaml
+      $ref: ./AdminProductOptionValue.yaml
   product:
-    $ref: ./BaseProduct.yaml
+    type: object
   product_id:
     type: string
     title: product_id
-    description: The parent's product id.
+    description: The ID of the product that the variant belongs to.
   calculated_price:
     $ref: ./BaseCalculatedPriceSet.yaml
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The parent's created at.
+    description: The date the variant was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The parent's updated at.
+    description: The date the variant was updated.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The parent's deleted at.
+    description: The date the variant was deleted.
   metadata:
     type: object
-    description: The parent's metadata.
+    description: The variant's metadata, can hold custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product variant's deletion.
 x-schemaName: AdminProductVariantDeleteResponse
 required:
   - id
@@ -9,7 +9,7 @@ properties:
   id:
     type: string
     title: id
-    description: The product's ID.
+    description: The product variant's ID.
   object:
     type: string
     title: object
@@ -17,6 +17,7 @@ properties:
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Product was deleted.
+    description: Whether the product variant was deleted.
+    default: variant
   parent:
     $ref: ./AdminProduct.yaml

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

@@ -1,5 +1,7 @@
 type: object
-description: SUMMARY
+description: >-
+  The created, updated, and deleted associations between variants and inventory
+  items.
 x-schemaName: AdminProductVariantInventoryBatchResponse
 required:
   - created
@@ -10,10 +12,12 @@ properties:
     oneOf:
       - $ref: ./AdminProductVariantInventoryLink.yaml
       - type: array
-        description: The product's created.
+        description: The created associations between product variants and inventory items.
         items:
           type: object
-          description: The created's details.
+          description: >-
+            A created association between a product variant and an inventory
+            item.
           x-schemaName: AdminProductVariantInventoryLink
           required:
             - productService
@@ -21,32 +25,34 @@ properties:
           properties:
             productService:
               type: object
-              description: The created's productservice.
+              description: The product variant's details.
               required:
                 - variant_id
               properties:
                 variant_id:
                   type: string
                   title: variant_id
-                  description: The productservice's variant id.
+                  description: The ID of the product variant.
             inventoryService:
               type: object
-              description: The created's inventoryservice.
+              description: The inventory item's details.
               required:
                 - inventory_item_id
               properties:
                 inventory_item_id:
                   type: string
                   title: inventory_item_id
-                  description: The inventoryservice's inventory item id.
+                  description: The ID of the inventory item.
   updated:
     oneOf:
       - $ref: ./AdminProductVariantInventoryLink.yaml
       - type: array
-        description: The product's updated.
+        description: The updated associations between product variants and inventory items.
         items:
           type: object
-          description: The updated's details.
+          description: >-
+            An updated association between a product variant and an inventory
+            item.
           x-schemaName: AdminProductVariantInventoryLink
           required:
             - productService
@@ -54,32 +60,34 @@ properties:
           properties:
             productService:
               type: object
-              description: The updated's productservice.
+              description: The product variant's details.
               required:
                 - variant_id
               properties:
                 variant_id:
                   type: string
                   title: variant_id
-                  description: The productservice's variant id.
+                  description: The ID of the product variant.
             inventoryService:
               type: object
-              description: The updated's inventoryservice.
+              description: The inventory item's details.
               required:
                 - inventory_item_id
               properties:
                 inventory_item_id:
                   type: string
                   title: inventory_item_id
-                  description: The inventoryservice's inventory item id.
+                  description: The ID of the inventory item.
   deleted:
     oneOf:
       - $ref: ./AdminProductVariantInventoryLink.yaml
       - type: array
-        description: SUMMARY
+        description: The deleted associations between product variants and inventory items.
         items:
           type: object
-          description: SUMMARY
+          description: >-
+            An deleted association between a product variant and an inventory
+            item.
           x-schemaName: AdminProductVariantInventoryLink
           required:
             - productService
@@ -87,21 +95,21 @@ properties:
           properties:
             productService:
               type: object
-              description: The deleted's productservice.
+              description: The product variant's details.
               required:
                 - variant_id
               properties:
                 variant_id:
                   type: string
                   title: variant_id
-                  description: The productservice's variant id.
+                  description: The ID of the product variant.
             inventoryService:
               type: object
-              description: The deleted's inventoryservice.
+              description: The inventory item's details.
               required:
                 - inventory_item_id
               properties:
                 inventory_item_id:
                   type: string
                   title: inventory_item_id
-                  description: The inventoryservice's inventory item id.
+                  description: The ID of the inventory item.

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

@@ -1,27 +1,27 @@
 type: object
-description: The product's ID.
+description: The details of an association between a product variant and an inventory item.
 x-schemaName: AdminProductVariantInventoryLink
 required:
-  - productService
+  - Product
-  - inventoryService
+  - Inventory
 properties:
-  productService:
+  Product:
     type: object
-    description: The id's productservice.
+    description: The product variant's details.
     required:
       - variant_id
     properties:
       variant_id:
         type: string
         title: variant_id
-        description: The productservice's variant id.
+        description: The ID of the product variant.
-  inventoryService:
+  Inventory:
     type: object
-    description: The id's inventoryservice.
+    description: The inventory item's details.
     required:
       - inventory_item_id
     properties:
       inventory_item_id:
         type: string
         title: inventory_item_id
-        description: The inventoryservice's inventory item id.
+        description: The ID of the inventory item.

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

@@ -1,5 +1,7 @@
 type: object
-description: SUMMARY
+description: >-
+  The details of the deleted associated between a product variant and an
+  inventory item.
 x-schemaName: AdminProductVariantInventoryLinkDeleteResponse
 required:
   - id
@@ -13,9 +15,10 @@ properties:
     type: string
     title: object
     description: The name of the deleted object.
+    default: variant-inventory-item-link
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Product was deleted.
+    description: Whether the association was deleted.
   parent:
     $ref: ./AdminProductVariant.yaml

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

@@ -1,872 +0,0 @@
-type: object
-description: SUMMARY
-x-schemaName: AdminProductVariantParams
-properties:
-  q:
-    type: string
-    title: q
-    description: The product's q.
-  id:
-    oneOf:
-      - type: string
-        title: id
-        description: The product's ID.
-      - type: array
-        description: The product's ID.
-        items:
-          type: string
-          title: id
-          description: The id's ID.
-  manage_inventory:
-    type: boolean
-    title: manage_inventory
-    description: The product's manage inventory.
-  allow_backorder:
-    type: boolean
-    title: allow_backorder
-    description: The product's allow backorder.
-  created_at:
-    type: object
-    description: The product's created at.
-    properties:
-      $and:
-        type: array
-        description: >-
-          Join query parameters with an AND condition. Each object's content is
-          the same type as the expected query parameters.
-        items:
-          type: object
-        title: $and
-      $or:
-        type: array
-        description: >-
-          Join query parameters with an OR condition. Each object's content is
-          the same type as the expected query parameters.
-        items:
-          type: object
-        title: $or
-      $eq:
-        oneOf:
-          - type: string
-            title: $eq
-            description: Filter by an exact match.
-          - type: array
-            description: Filter by an exact match.
-            items:
-              type: string
-              title: $eq
-              description: Filter by an exact match.
-      $ne:
-        type: string
-        title: $ne
-        description: Filter by values not equal to this parameter.
-      $in:
-        type: array
-        description: Filter by values in this array.
-        items:
-          type: string
-          title: $in
-          description: Filter by values in this array.
-      $nin:
-        type: array
-        description: Filter by values not in this array.
-        items:
-          type: string
-          title: $nin
-          description: Filter by values not in this array.
-      $not:
-        oneOf:
-          - type: string
-            title: $not
-            description: Filter by values not matching the conditions in this parameter.
-          - type: object
-            description: Filter by values not matching the conditions in this parameter.
-            properties:
-              $and:
-                type: array
-                description: >-
-                  Join query parameters with an AND condition. Each object's
-                  content is the same type as the expected query parameters.
-                items:
-                  type: object
-                title: $and
-              $or:
-                type: array
-                description: >-
-                  Join query parameters with an OR condition. Each object's
-                  content is the same type as the expected query parameters.
-                items:
-                  type: object
-                title: $or
-              $eq:
-                oneOf:
-                  - type: string
-                    title: $eq
-                    description: Filter by an exact match.
-                  - type: array
-                    description: Filter by an exact match.
-                    items:
-                      type: string
-                      title: $eq
-                      description: Filter by an exact match.
-              $ne:
-                type: string
-                title: $ne
-                description: Filter by values not equal to this parameter.
-              $in:
-                type: array
-                description: Filter by values in this array.
-                items:
-                  type: string
-                  title: $in
-                  description: Filter by values in this array.
-              $nin:
-                type: array
-                description: Filter by values not in this array.
-                items:
-                  type: string
-                  title: $nin
-                  description: Filter by values not in this array.
-              $not:
-                oneOf:
-                  - type: string
-                    title: $not
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                  - type: object
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                  - type: array
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                    items:
-                      type: string
-                      title: $not
-                      description: >-
-                        Filter by values not matching the conditions in this
-                        parameter.
-              $gt:
-                type: string
-                title: $gt
-                description: >-
-                  Filter by values greater than this parameter. Useful for
-                  numbers and dates only.
-              $gte:
-                type: string
-                title: $gte
-                description: >-
-                  Filter by values greater than or equal to this parameter.
-                  Useful for numbers and dates only.
-              $lt:
-                type: string
-                title: $lt
-                description: >-
-                  Filter by values less than this parameter. Useful for numbers
-                  and dates only.
-              $lte:
-                type: string
-                title: $lte
-                description: >-
-                  Filter by values less than or equal to this parameter. Useful
-                  for numbers and dates only.
-              $like:
-                type: string
-                title: $like
-                description: Apply a `like` filter. Useful for strings only.
-              $re:
-                type: string
-                title: $re
-                description: Apply a regex filter. Useful for strings only.
-              $ilike:
-                type: string
-                title: $ilike
-                description: >-
-                  Apply a case-insensitive `like` filter. Useful for strings
-                  only.
-              $fulltext:
-                type: string
-                title: $fulltext
-                description: Filter to apply on full-text properties.
-              $overlap:
-                type: array
-                description: >-
-                  Filter arrays that have overlapping values with this
-                  parameter.
-                items:
-                  type: string
-                  title: $overlap
-                  description: >-
-                    Filter arrays that have overlapping values with this
-                    parameter.
-              $contains:
-                type: array
-                description: >-
-                  Filter arrays that contain some of the values of this
-                  parameter.
-                items:
-                  type: string
-                  title: $contains
-                  description: >-
-                    Filter arrays that contain some of the values of this
-                    parameter.
-              $contained:
-                type: array
-                description: Filter arrays that contain all values of this parameter.
-                items:
-                  type: string
-                  title: $contained
-                  description: Filter arrays that contain all values of this parameter.
-              $exists:
-                type: boolean
-                title: $exists
-                description: >-
-                  Filter by whether a value for this parameter exists (not
-                  `null`).
-          - type: array
-            description: Filter by values not matching the conditions in this parameter.
-            items:
-              type: string
-              title: $not
-              description: Filter by values not matching the conditions in this parameter.
-      $gt:
-        type: string
-        title: $gt
-        description: >-
-          Filter by values greater than this parameter. Useful for numbers and
-          dates only.
-      $gte:
-        type: string
-        title: $gte
-        description: >-
-          Filter by values greater than or equal to this parameter. Useful for
-          numbers and dates only.
-      $lt:
-        type: string
-        title: $lt
-        description: >-
-          Filter by values less than this parameter. Useful for numbers and
-          dates only.
-      $lte:
-        type: string
-        title: $lte
-        description: >-
-          Filter by values less than or equal to this parameter. Useful for
-          numbers and dates only.
-      $like:
-        type: string
-        title: $like
-        description: Apply a `like` filter. Useful for strings only.
-      $re:
-        type: string
-        title: $re
-        description: Apply a regex filter. Useful for strings only.
-      $ilike:
-        type: string
-        title: $ilike
-        description: Apply a case-insensitive `like` filter. Useful for strings only.
-      $fulltext:
-        type: string
-        title: $fulltext
-        description: Filter to apply on full-text properties.
-      $overlap:
-        type: array
-        description: Filter arrays that have overlapping values with this parameter.
-        items:
-          type: string
-          title: $overlap
-          description: Filter arrays that have overlapping values with this parameter.
-      $contains:
-        type: array
-        description: Filter arrays that contain some of the values of this parameter.
-        items:
-          type: string
-          title: $contains
-          description: Filter arrays that contain some of the values of this parameter.
-      $contained:
-        type: array
-        description: Filter arrays that contain all values of this parameter.
-        items:
-          type: string
-          title: $contained
-          description: Filter arrays that contain all values of this parameter.
-      $exists:
-        type: boolean
-        title: $exists
-        description: Filter by whether a value for this parameter exists (not `null`).
-  updated_at:
-    type: object
-    description: The product's updated at.
-    properties:
-      $and:
-        type: array
-        description: >-
-          Join query parameters with an AND condition. Each object's content is
-          the same type as the expected query parameters.
-        items:
-          type: object
-        title: $and
-      $or:
-        type: array
-        description: >-
-          Join query parameters with an OR condition. Each object's content is
-          the same type as the expected query parameters.
-        items:
-          type: object
-        title: $or
-      $eq:
-        oneOf:
-          - type: string
-            title: $eq
-            description: Filter by an exact match.
-          - type: array
-            description: Filter by an exact match.
-            items:
-              type: string
-              title: $eq
-              description: Filter by an exact match.
-      $ne:
-        type: string
-        title: $ne
-        description: Filter by values not equal to this parameter.
-      $in:
-        type: array
-        description: Filter by values in this array.
-        items:
-          type: string
-          title: $in
-          description: Filter by values in this array.
-      $nin:
-        type: array
-        description: Filter by values not in this array.
-        items:
-          type: string
-          title: $nin
-          description: Filter by values not in this array.
-      $not:
-        oneOf:
-          - type: string
-            title: $not
-            description: Filter by values not matching the conditions in this parameter.
-          - type: object
-            description: Filter by values not matching the conditions in this parameter.
-            properties:
-              $and:
-                type: array
-                description: >-
-                  Join query parameters with an AND condition. Each object's
-                  content is the same type as the expected query parameters.
-                items:
-                  type: object
-                title: $and
-              $or:
-                type: array
-                description: >-
-                  Join query parameters with an OR condition. Each object's
-                  content is the same type as the expected query parameters.
-                items:
-                  type: object
-                title: $or
-              $eq:
-                oneOf:
-                  - type: string
-                    title: $eq
-                    description: Filter by an exact match.
-                  - type: array
-                    description: Filter by an exact match.
-                    items:
-                      type: string
-                      title: $eq
-                      description: Filter by an exact match.
-              $ne:
-                type: string
-                title: $ne
-                description: Filter by values not equal to this parameter.
-              $in:
-                type: array
-                description: Filter by values in this array.
-                items:
-                  type: string
-                  title: $in
-                  description: Filter by values in this array.
-              $nin:
-                type: array
-                description: Filter by values not in this array.
-                items:
-                  type: string
-                  title: $nin
-                  description: Filter by values not in this array.
-              $not:
-                oneOf:
-                  - type: string
-                    title: $not
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                  - type: object
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                  - type: array
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                    items:
-                      type: string
-                      title: $not
-                      description: >-
-                        Filter by values not matching the conditions in this
-                        parameter.
-              $gt:
-                type: string
-                title: $gt
-                description: >-
-                  Filter by values greater than this parameter. Useful for
-                  numbers and dates only.
-              $gte:
-                type: string
-                title: $gte
-                description: >-
-                  Filter by values greater than or equal to this parameter.
-                  Useful for numbers and dates only.
-              $lt:
-                type: string
-                title: $lt
-                description: >-
-                  Filter by values less than this parameter. Useful for numbers
-                  and dates only.
-              $lte:
-                type: string
-                title: $lte
-                description: >-
-                  Filter by values less than or equal to this parameter. Useful
-                  for numbers and dates only.
-              $like:
-                type: string
-                title: $like
-                description: Apply a `like` filter. Useful for strings only.
-              $re:
-                type: string
-                title: $re
-                description: Apply a regex filter. Useful for strings only.
-              $ilike:
-                type: string
-                title: $ilike
-                description: >-
-                  Apply a case-insensitive `like` filter. Useful for strings
-                  only.
-              $fulltext:
-                type: string
-                title: $fulltext
-                description: Filter to apply on full-text properties.
-              $overlap:
-                type: array
-                description: >-
-                  Filter arrays that have overlapping values with this
-                  parameter.
-                items:
-                  type: string
-                  title: $overlap
-                  description: >-
-                    Filter arrays that have overlapping values with this
-                    parameter.
-              $contains:
-                type: array
-                description: >-
-                  Filter arrays that contain some of the values of this
-                  parameter.
-                items:
-                  type: string
-                  title: $contains
-                  description: >-
-                    Filter arrays that contain some of the values of this
-                    parameter.
-              $contained:
-                type: array
-                description: Filter arrays that contain all values of this parameter.
-                items:
-                  type: string
-                  title: $contained
-                  description: Filter arrays that contain all values of this parameter.
-              $exists:
-                type: boolean
-                title: $exists
-                description: >-
-                  Filter by whether a value for this parameter exists (not
-                  `null`).
-          - type: array
-            description: Filter by values not matching the conditions in this parameter.
-            items:
-              type: string
-              title: $not
-              description: Filter by values not matching the conditions in this parameter.
-      $gt:
-        type: string
-        title: $gt
-        description: >-
-          Filter by values greater than this parameter. Useful for numbers and
-          dates only.
-      $gte:
-        type: string
-        title: $gte
-        description: >-
-          Filter by values greater than or equal to this parameter. Useful for
-          numbers and dates only.
-      $lt:
-        type: string
-        title: $lt
-        description: >-
-          Filter by values less than this parameter. Useful for numbers and
-          dates only.
-      $lte:
-        type: string
-        title: $lte
-        description: >-
-          Filter by values less than or equal to this parameter. Useful for
-          numbers and dates only.
-      $like:
-        type: string
-        title: $like
-        description: Apply a `like` filter. Useful for strings only.
-      $re:
-        type: string
-        title: $re
-        description: Apply a regex filter. Useful for strings only.
-      $ilike:
-        type: string
-        title: $ilike
-        description: Apply a case-insensitive `like` filter. Useful for strings only.
-      $fulltext:
-        type: string
-        title: $fulltext
-        description: Filter to apply on full-text properties.
-      $overlap:
-        type: array
-        description: Filter arrays that have overlapping values with this parameter.
-        items:
-          type: string
-          title: $overlap
-          description: Filter arrays that have overlapping values with this parameter.
-      $contains:
-        type: array
-        description: Filter arrays that contain some of the values of this parameter.
-        items:
-          type: string
-          title: $contains
-          description: Filter arrays that contain some of the values of this parameter.
-      $contained:
-        type: array
-        description: Filter arrays that contain all values of this parameter.
-        items:
-          type: string
-          title: $contained
-          description: Filter arrays that contain all values of this parameter.
-      $exists:
-        type: boolean
-        title: $exists
-        description: Filter by whether a value for this parameter exists (not `null`).
-  deleted_at:
-    type: object
-    description: The product's deleted at.
-    properties:
-      $and:
-        type: array
-        description: >-
-          Join query parameters with an AND condition. Each object's content is
-          the same type as the expected query parameters.
-        items:
-          type: object
-        title: $and
-      $or:
-        type: array
-        description: >-
-          Join query parameters with an OR condition. Each object's content is
-          the same type as the expected query parameters.
-        items:
-          type: object
-        title: $or
-      $eq:
-        oneOf:
-          - type: string
-            title: $eq
-            description: Filter by an exact match.
-          - type: array
-            description: Filter by an exact match.
-            items:
-              type: string
-              title: $eq
-              description: Filter by an exact match.
-      $ne:
-        type: string
-        title: $ne
-        description: Filter by values not equal to this parameter.
-      $in:
-        type: array
-        description: Filter by values in this array.
-        items:
-          type: string
-          title: $in
-          description: Filter by values in this array.
-      $nin:
-        type: array
-        description: Filter by values not in this array.
-        items:
-          type: string
-          title: $nin
-          description: Filter by values not in this array.
-      $not:
-        oneOf:
-          - type: string
-            title: $not
-            description: Filter by values not matching the conditions in this parameter.
-          - type: object
-            description: Filter by values not matching the conditions in this parameter.
-            properties:
-              $and:
-                type: array
-                description: >-
-                  Join query parameters with an AND condition. Each object's
-                  content is the same type as the expected query parameters.
-                items:
-                  type: object
-                title: $and
-              $or:
-                type: array
-                description: >-
-                  Join query parameters with an OR condition. Each object's
-                  content is the same type as the expected query parameters.
-                items:
-                  type: object
-                title: $or
-              $eq:
-                oneOf:
-                  - type: string
-                    title: $eq
-                    description: Filter by an exact match.
-                  - type: array
-                    description: Filter by an exact match.
-                    items:
-                      type: string
-                      title: $eq
-                      description: Filter by an exact match.
-              $ne:
-                type: string
-                title: $ne
-                description: Filter by values not equal to this parameter.
-              $in:
-                type: array
-                description: Filter by values in this array.
-                items:
-                  type: string
-                  title: $in
-                  description: Filter by values in this array.
-              $nin:
-                type: array
-                description: Filter by values not in this array.
-                items:
-                  type: string
-                  title: $nin
-                  description: Filter by values not in this array.
-              $not:
-                oneOf:
-                  - type: string
-                    title: $not
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                  - type: object
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                  - type: array
-                    description: >-
-                      Filter by values not matching the conditions in this
-                      parameter.
-                    items:
-                      type: string
-                      title: $not
-                      description: >-
-                        Filter by values not matching the conditions in this
-                        parameter.
-              $gt:
-                type: string
-                title: $gt
-                description: >-
-                  Filter by values greater than this parameter. Useful for
-                  numbers and dates only.
-              $gte:
-                type: string
-                title: $gte
-                description: >-
-                  Filter by values greater than or equal to this parameter.
-                  Useful for numbers and dates only.
-              $lt:
-                type: string
-                title: $lt
-                description: >-
-                  Filter by values less than this parameter. Useful for numbers
-                  and dates only.
-              $lte:
-                type: string
-                title: $lte
-                description: >-
-                  Filter by values less than or equal to this parameter. Useful
-                  for numbers and dates only.
-              $like:
-                type: string
-                title: $like
-                description: Apply a `like` filter. Useful for strings only.
-              $re:
-                type: string
-                title: $re
-                description: Apply a regex filter. Useful for strings only.
-              $ilike:
-                type: string
-                title: $ilike
-                description: >-
-                  Apply a case-insensitive `like` filter. Useful for strings
-                  only.
-              $fulltext:
-                type: string
-                title: $fulltext
-                description: Filter to apply on full-text properties.
-              $overlap:
-                type: array
-                description: >-
-                  Filter arrays that have overlapping values with this
-                  parameter.
-                items:
-                  type: string
-                  title: $overlap
-                  description: >-
-                    Filter arrays that have overlapping values with this
-                    parameter.
-              $contains:
-                type: array
-                description: >-
-                  Filter arrays that contain some of the values of this
-                  parameter.
-                items:
-                  type: string
-                  title: $contains
-                  description: >-
-                    Filter arrays that contain some of the values of this
-                    parameter.
-              $contained:
-                type: array
-                description: Filter arrays that contain all values of this parameter.
-                items:
-                  type: string
-                  title: $contained
-                  description: Filter arrays that contain all values of this parameter.
-              $exists:
-                type: boolean
-                title: $exists
-                description: >-
-                  Filter by whether a value for this parameter exists (not
-                  `null`).
-          - type: array
-            description: Filter by values not matching the conditions in this parameter.
-            items:
-              type: string
-              title: $not
-              description: Filter by values not matching the conditions in this parameter.
-      $gt:
-        type: string
-        title: $gt
-        description: >-
-          Filter by values greater than this parameter. Useful for numbers and
-          dates only.
-      $gte:
-        type: string
-        title: $gte
-        description: >-
-          Filter by values greater than or equal to this parameter. Useful for
-          numbers and dates only.
-      $lt:
-        type: string
-        title: $lt
-        description: >-
-          Filter by values less than this parameter. Useful for numbers and
-          dates only.
-      $lte:
-        type: string
-        title: $lte
-        description: >-
-          Filter by values less than or equal to this parameter. Useful for
-          numbers and dates only.
-      $like:
-        type: string
-        title: $like
-        description: Apply a `like` filter. Useful for strings only.
-      $re:
-        type: string
-        title: $re
-        description: Apply a regex filter. Useful for strings only.
-      $ilike:
-        type: string
-        title: $ilike
-        description: Apply a case-insensitive `like` filter. Useful for strings only.
-      $fulltext:
-        type: string
-        title: $fulltext
-        description: Filter to apply on full-text properties.
-      $overlap:
-        type: array
-        description: Filter arrays that have overlapping values with this parameter.
-        items:
-          type: string
-          title: $overlap
-          description: Filter arrays that have overlapping values with this parameter.
-      $contains:
-        type: array
-        description: Filter arrays that contain some of the values of this parameter.
-        items:
-          type: string
-          title: $contains
-          description: Filter arrays that contain some of the values of this parameter.
-      $contained:
-        type: array
-        description: Filter arrays that contain all values of this parameter.
-        items:
-          type: string
-          title: $contained
-          description: Filter arrays that contain all values of this parameter.
-      $exists:
-        type: boolean
-        title: $exists
-        description: Filter by whether a value for this parameter exists (not `null`).
-  limit:
-    type: number
-    title: limit
-    description: The product's limit.
-  offset:
-    type: number
-    title: offset
-    description: The product's offset.
-  order:
-    type: string
-    title: order
-    description: The product's order.
-  fields:
-    type: string
-    title: fields
-    description: The product's fields.
-  $and:
-    type: array
-    description: >-
-      Join query parameters with an AND condition. Each object's content is the
-      same type as the expected query parameters.
-    items:
-      type: object
-    title: $and
-  $or:
-    type: array
-    description: >-
-      Join query parameters with an OR condition. Each object's content is the
-      same type as the expected query parameters.
-    items:
-      type: object
-    title: $or

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product variant's details.
 x-schemaName: AdminProductVariantResponse
 required:
   - variant

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

@@ -4,6 +4,13 @@ x-schemaName: AdminPromotion
 required:
   - id
 properties:
+  application_method:
+    type: object
+  rules:
+    type: array
+    description: The promotion's rules.
+    items:
+      $ref: ./AdminPromotionRule.yaml
   id:
     type: string
     title: id
@@ -12,6 +19,7 @@ properties:
     type: string
     title: code
     description: The promotion's code.
+    example: OFF50
   type:
     type: string
     description: The promotion's type.
@@ -21,17 +29,12 @@ properties:
   is_automatic:
     type: boolean
     title: is_automatic
-    description: The promotion's is automatic.
+    description: >-
-  application_method:
+      Whether the promotion is applied on a cart automatically if it matches the
-    $ref: ./BaseApplicationMethod.yaml
+      promotion's rules.
-  rules:
-    type: array
-    description: The promotion's rules.
-    items:
-      $ref: ./BasePromotionRule.yaml
   campaign_id:
     type: string
     title: campaign_id
-    description: The promotion's campaign id.
+    description: The ID of the campaign this promotion belongs to.
   campaign:
     $ref: ./AdminCampaign.yaml

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The promotion's details.
 x-schemaName: AdminPromotionResponse
 required:
   - promotion

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

@@ -1,5 +1,5 @@
 type: object
-description: The updated's details.
+description: The promotion rule's details.
 x-schemaName: AdminPromotionRule
 required:
   - id
@@ -8,18 +8,19 @@ properties:
   id:
     type: string
     title: id
-    description: The updated's ID.
+    description: The promotion rule's ID.
   description:
     type: string
     title: description
-    description: The updated's description.
+    description: The promotion rule's description.
   attribute:
     type: string
     title: attribute
-    description: The updated's attribute.
+    description: The promotion rule's attribute.
+    example: customer_group_id
   operator:
     type: string
-    description: The updated's operator.
+    description: The rule's operator.
     enum:
       - gt
       - lt
@@ -30,6 +31,8 @@ properties:
       - gte
   values:
     type: array
-    description: The updated's values.
+    description: The rule's values.
+    example:
+      - cusgroup_123
     items:
       $ref: ./BasePromotionRuleValue.yaml

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

@@ -0,0 +1,38 @@
+type: object
+description: The refund's details.
+x-schemaName: AdminRefund
+required:
+  - id
+  - amount
+  - created_at
+  - payment
+properties:
+  id:
+    type: string
+    title: id
+    description: The refund's ID.
+  amount:
+    type: number
+    title: amount
+    description: The refund's amount.
+  refund_reason_id:
+    type: string
+    title: refund_reason_id
+    description: The ID of the refund reason.
+  note:
+    type: string
+    title: note
+    description: More details about the refund.
+  created_at:
+    type: string
+    format: date-time
+    title: created_at
+    description: The date the refund was created.
+  created_by:
+    type: string
+    title: created_by
+    description: The ID of the user that created the refund.
+  payment:
+    $ref: ./BasePayment.yaml
+  refund_reason:
+    $ref: ./RefundReason.yaml

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

@@ -22,14 +22,14 @@ properties:
     description: The refund reason's description.
   metadata:
     type: object
-    description: The refund reason's metadata.
+    description: The refund reason's metadata, can hold custom key-value pairs.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The refund reason's created at.
+    description: The date the refund reason was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The refund reason's updated at.
+    description: The date the refund reason was updated.

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

@@ -2,9 +2,9 @@ type: object
 description: The region's details.
 x-schemaName: AdminRegion
 required:
-  - id
   - name
   - currency_code
+  - id
 properties:
   id:
     type: string
@@ -18,15 +18,16 @@ properties:
     type: string
     title: currency_code
     description: The region's currency code.
+    example: usd
   automatic_taxes:
     type: boolean
     title: automatic_taxes
-    description: The region's automatic taxes.
+    description: Whether taxes are applied automatically during checkout.
   countries:
     type: array
     description: The region's countries.
     items:
-      $ref: ./BaseRegionCountry.yaml
+      $ref: ./AdminRegionCountry.yaml
   payment_providers:
     type: array
     description: The region's payment providers.
@@ -34,14 +35,14 @@ properties:
       $ref: ./AdminPaymentProvider.yaml
   metadata:
     type: object
-    description: The region's metadata.
+    description: The region's metadata, can hold custom key-value pairs.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The region's created at.
+    description: The date the region was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The region's updated at.
+    description: The date the region was updated.

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

@@ -1,3 +1,33 @@
 type: object
-description: The billing address's country.
+description: The country's details.
 x-schemaName: AdminRegionCountry
+required:
+  - id
+properties:
+  id:
+    type: string
+    title: id
+    description: The country's ID.
+  iso_2:
+    type: string
+    title: iso_2
+    description: The country's iso 2.
+    example: us
+  iso_3:
+    type: string
+    title: iso_3
+    description: The country's iso 3.
+    example: usa
+  num_code:
+    type: string
+    title: num_code
+    description: The country's num code.
+    example: 840
+  name:
+    type: string
+    title: name
+    description: The country's name.
+  display_name:
+    type: string
+    title: display_name
+    description: The country's display name.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The region's details.
 x-schemaName: AdminRegionResponse
 required:
   - region

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

@@ -9,7 +9,6 @@ required:
   - external_id
   - description
   - inventory_item_id
-  - inventory_item
 properties:
   id:
     type: string
@@ -18,11 +17,11 @@ properties:
   line_item_id:
     type: string
     title: line_item_id
-    description: The reservation's line item id.
+    description: The ID of the line item this reservation is for.
   location_id:
     type: string
     title: location_id
-    description: The reservation's location id.
+    description: The ID of the location the quantity is reserved from.
   quantity:
     type: number
     title: quantity
@@ -30,7 +29,7 @@ properties:
   external_id:
     type: string
     title: external_id
-    description: The reservation's external id.
+    description: An ID in an external system
   description:
     type: string
     title: description
@@ -38,29 +37,28 @@ properties:
   inventory_item_id:
     type: string
     title: inventory_item_id
-    description: The reservation's inventory item id.
+    description: The ID of the inventory item this reservation is associated with.
   inventory_item:
-    type: object
+    $ref: ./AdminInventoryItem.yaml
-    description: The reservation's inventory item.
   metadata:
     type: object
-    description: The reservation's metadata.
+    description: The reservation's metadata, can hold custom key-value pairs.
   created_by:
     type: string
     title: created_by
-    description: The reservation's created by.
+    description: The ID of the user that created this reservation.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The reservation's deleted at.
+    description: The date this reservation was deleted.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The reservation's created at.
+    description: The date this reservation was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The reservation's updated at.
+    description: The date this reservation was updated.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The reservation's details.
 x-schemaName: AdminReservationResponse
 required:
   - reservation

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

@@ -1,12 +1,12 @@
 type: object
-description: The exchange's return.
+description: The return's details.
 x-schemaName: AdminReturn
 required:
+  - items
   - id
   - order_id
   - order_version
   - display_id
-  - items
   - received_at
   - created_at
   - canceled_at
@@ -15,14 +15,37 @@ properties:
     type: string
     title: id
     description: The return's ID.
+  status:
+    type: string
+    description: The return's status.
+    enum:
+      - canceled
+      - requested
+      - received
+      - partially_received
+  refund_amount:
+    type: number
+    title: refund_amount
+    description: The amount refunded by this return.
   order_id:
     type: string
     title: order_id
-    description: The return's order id.
+    description: The ID of the associated order.
-  status:
+  items:
+    type: array
+    description: The return's items.
+    items:
+      $ref: ./AdminReturnItem.yaml
+  created_at:
     type: string
-    title: status
+    format: date-time
-    description: The return's status.
+    title: created_at
+    description: The date the return was created.
+  canceled_at:
+    type: string
+    title: canceled_at
+    description: The date the return was canceled.
+    format: date-time
   exchange_id:
     type: string
     title: exchange_id
@@ -46,26 +69,10 @@ properties:
   no_notification:
     type: boolean
     title: no_notification
-    description: The return's no notification.
+    description: >-
-  refund_amount:
+      Whether the customer should receive notifications about the return's
-    type: number
+      updates.
-    title: refund_amount
-    description: The return's refund amount.
-  items:
-    type: array
-    description: The return's items.
-    items:
-      $ref: ./BaseReturnItem.yaml
   received_at:
     type: string
     title: received_at
-    description: The return's received at.
+    description: The date the return was received.
-  created_at:
-    type: string
-    format: date-time
-    title: created_at
-    description: The return's created at.
-  canceled_at:
-    type: string
-    title: canceled_at
-    description: The return's canceled at.

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

@@ -1,5 +1,5 @@
 type: object
-description: The return item's return items.
+description: The return item's details.
 x-schemaName: AdminReturnItem
 required:
   - id
@@ -20,27 +20,31 @@ properties:
   received_quantity:
     type: number
     title: received_quantity
-    description: The return item's received quantity.
+    description: >-
+      The received quantity of the item. This quantity is added to the stocked
+      inventory quantity of the item.
   damaged_quantity:
     type: number
     title: damaged_quantity
-    description: The return item's damaged quantity.
+    description: >-
+      The received damaged quantity of the item, which isn't added to the
+      stocked inventory quantity of the item.
   reason_id:
     type: string
     title: reason_id
-    description: The return item's reason id.
+    description: The ID of the return reason associated with the item.
   note:
     type: string
     title: note
-    description: The return item's note.
+    description: A note about why the item was returned.
   item_id:
     type: string
     title: item_id
-    description: The return item's item id.
+    description: The ID of the associated order item.
   return_id:
     type: string
     title: return_id
-    description: The return item's return id.
+    description: The ID of the return this return item belongs to.
   metadata:
     type: object
-    description: The return item's metadata.
+    description: The return item's metadata, can hold custom key-value pairs.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of a return and a preview of the order once the return is applied.
 x-schemaName: AdminReturnPreviewResponse
 required:
   - order_preview

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

@@ -26,14 +26,14 @@ properties:
     description: The return reason's description.
   metadata:
     type: object
-    description: The return reason's metadata.
+    description: The return reason's metadata, can hold custom key-value pairs.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The return reason's created at.
+    description: The date the return reason was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The return reason's updated at.
+    description: The date the return reason was updated.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the return reason deletion.
 x-schemaName: AdminReturnReasonDeleteResponse
 required:
   - id
@@ -18,4 +18,4 @@ properties:
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Return Reason was deleted.
+    description: Whether the return reason was deleted.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of return reasons.
 x-schemaName: AdminReturnReasonListResponse
 required:
   - limit
@@ -10,17 +10,17 @@ properties:
   limit:
     type: number
     title: limit
-    description: The return reason's limit.
+    description: The maximum number of items returned.
   offset:
     type: number
     title: offset
-    description: The return reason's offset.
+    description: The number of items skipped before retrieving the returned items.
   count:
     type: number
     title: count
-    description: The return reason's count.
+    description: The total number of items.
   return_reasons:
     type: array
-    description: The return reason's return reasons.
+    description: The list of return reasons.
     items:
       $ref: ./AdminReturnReason.yaml

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The return reason's details.
 x-schemaName: AdminReturnReasonResponse
 required:
   - return_reason

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The return's details.
 x-schemaName: AdminReturnResponse
 required:
   - return

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

@@ -1,8 +1,10 @@
 type: object
-description: SUMMARY
+description: The details of revoking the API key.
 x-schemaName: AdminRevokeApiKey
 properties:
   revoke_in:
     type: number
     title: revoke_in
-    description: The api key's revoke in.
+    description: >-
+      The time in seconds to revoke the API key after. If not set, the API key
+      is revoked immediately.

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

@@ -1,39 +1,27 @@
 type: object
-description: The attribute's attributes.
+description: The details of a potential rule attribute.
 x-schemaName: AdminRuleAttributeOption
 required:
   - id
   - value
   - label
-  - field_type
-  - required
-  - disguised
   - operators
 properties:
   id:
     type: string
     title: id
-    description: The attribute's ID.
+    description: The rule attribute's ID, which is a rule's `attribute` it refers to.
+    example: customer_group
   value:
     type: string
     title: value
-    description: The attribute's value.
+    description: The rule attribute's value.
+    example: customer.groups.id
   label:
     type: string
     title: label
-    description: The attribute's label.
+    description: The rule attribute option's label.
-  field_type:
+    example: Customer Group
-    type: string
-    title: field_type
-    description: The attribute's field type.
-  required:
-    type: boolean
-    title: required
-    description: The attribute's required.
-  disguised:
-    type: boolean
-    title: disguised
-    description: The attribute's disguised.
   operators:
     type: array
     description: The attribute's operators.

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

@@ -1,20 +1,17 @@
 type: object
-description: The value's values.
+description: The details of a potential rule value.
 x-schemaName: AdminRuleValueOption
 required:
-  - id
   - value
   - label
 properties:
-  id:
-    type: string
-    title: id
-    description: The value's ID.
   value:
     type: string
     title: value
-    description: The value's details.
+    description: The rule value's value.
+    example: reg_123
   label:
     type: string
     title: label
-    description: The value's label.
+    description: The rule value's label.
+    example: Europe Region

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

@@ -1,5 +1,5 @@
 type: object
-description: The order's sales channel.
+description: The sales channel's details.
 x-schemaName: AdminSalesChannel
 required:
   - id
@@ -26,22 +26,22 @@ properties:
   is_disabled:
     type: boolean
     title: is_disabled
-    description: The sales channel's is disabled.
+    description: Whether the sales channel is disabled.
   metadata:
     type: object
-    description: The sales channel's metadata.
+    description: The sales channel's metadata, can hold custom key-value pairs.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The sales channel's created at.
+    description: The date the sales channel was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The sales channel's updated at.
+    description: The date the sales channel was updated.
   deleted_at:
     type: string
     format: date-time
     title: deleted_at
-    description: The sales channel's deleted at.
+    description: The date the sales channel was deleted.

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

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of deleting a sales channel.
 x-schemaName: AdminSalesChannelDeleteResponse
 required:
   - id
@@ -18,4 +18,4 @@ properties:
   deleted:
     type: boolean
     title: deleted
-    description: Whether the Sales Channel was deleted.
+    description: Whether the sales channel was deleted.