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>

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

@@ -1,5 +1,5 @@
 type: object
-description: The order preview's order change.
+description: The order change's details.
 x-schemaName: OrderChange
 required:
   - id
@@ -34,10 +34,12 @@ properties:
   version:
     type: number
     title: version
-    description: The order change's 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 change type.
+    description: The order change's type.
     enum:
       - return
       - exchange
@@ -46,23 +48,23 @@ properties:
   order_id:
     type: string
     title: order_id
-    description: The order change's order id.
+    description: The ID of the order this change applies on.
   return_id:
     type: string
     title: return_id
-    description: The order change's return id.
+    description: The ID of the associated return.
   exchange_id:
     type: string
     title: exchange_id
-    description: The order change's exchange id.
+    description: The ID of the associated exchange.
   claim_id:
     type: string
     title: claim_id
-    description: The order change's claim id.
+    description: The ID of the associated claim.
   order:
     type: object
   return_order:
-    $ref: ./Return.yaml
+    type: object
   exchange:
     $ref: ./OrderExchange.yaml
   claim:
@@ -74,74 +76,63 @@ properties:
       $ref: ./OrderChangeAction.yaml
   status:
     type: string
-    title: status
     description: The order change's status.
+    enum:
+      - canceled
+      - requested
+      - pending
+      - confirmed
+      - declined
   requested_by:
     type: string
     title: requested_by
-    description: The order change's requested by.
+    description: The ID of the user that requested the change.
   requested_at:
-    oneOf:
-      - type: string
-        title: requested_at
-        description: The order change's requested at.
-      - type: string
-        title: requested_at
-        description: The order change's requested at.
-        format: date-time
+    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 order change's confirmed by.
+    description: The ID of the user that confirmed the order change.
   confirmed_at:
-    oneOf:
-      - type: string
-        title: confirmed_at
-        description: The order change's confirmed at.
-      - type: string
-        title: confirmed_at
-        description: The order change's confirmed at.
-        format: date-time
+    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 order change's declined by.
+    description: The ID of the user that declined the order change.
   declined_reason:
     type: string
     title: declined_reason
-    description: The order change's declined reason.
+    description: The reason the order change was declined.
   metadata:
     type: object
-    description: The order change's metadata.
+    description: The order change's metadata, can hold custom key-value pairs.
   declined_at:
-    oneOf:
-      - type: string
-        title: declined_at
-        description: The order change's declined at.
-      - type: string
-        title: declined_at
-        description: The order change's declined at.
-        format: date-time
+    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 order change's canceled by.
+    description: The ID of the user that canceled the order change.
   canceled_at:
-    oneOf:
-      - type: string
-        title: canceled_at
-        description: The order change's canceled at.
-      - type: string
-        title: canceled_at
-        description: The order change's canceled at.
-        format: date-time
+    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 order change's created at.
+    description: The date the order change was created.
   updated_at:
     type: string
     format: date-time
     title: updated_at
-    description: The order change's updated at.
+    description: The date the order change was updated.