docs: fixes to the API reference (#2570)

packages/medusa/src/models/order-edit.ts

@@ -141,11 +141,11 @@ export class OrderEdit extends BaseEntity {
  *     description: The ID of the order that is edited
  *     example: order_01G2SG30J8C85S4A5CHM2S1NS2
  *   order:
- *     description: Order object
+ *     description: Available if the relation `order` is expanded.
  *     $ref: "#/components/schemas/order"
  *   changes:
  *     type: array
- *     description: Line item changes array.
+ *     description: Available if the relation `changes` is expanded.
  *     items:
  *       $ref: "#/components/schemas/order_item_change"
  *   internal_note:
@@ -211,9 +211,33 @@ export class OrderEdit extends BaseEntity {
  *     type: integer
  *     description: The difference between the total amount of the order and total amount of edited order.
  *     example: 8200
+ *   status:
+ *     type: string
+ *     description: The status of the order edit.
+ *     enum:
+ *       - confirmed
+ *       - declined
+ *       - requested
+ *       - created
+ *       - canceled
  *   items:
  *     type: array
- *     description: Computed line items from the changes.
+ *     description: Available if the relation `items` is expanded.
  *     items:
  *       $ref: "#/components/schemas/line_item"
+ *   payment_collection_id:
+ *     type: string
+ *     description: The ID of the payment collection
+ *     example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
+ *   payment_collection:
+ *     description: Available if the relation `payment_collection` is expanded.
+ *     $ref: "#/components/schemas/payment_collection"
+ *   created_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was created."
+ *     format: date-time
+ *   updated_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was updated."
+ *     format: date-time
  */

packages/medusa/src/models/order-item-change.ts

@@ -73,7 +73,7 @@ export class OrderItemChange extends SoftDeletableEntity {
  *     example: oic_01G8TJSYT9M6AVS5N4EMNFS1EK
  *   type:
  *     type: string
- *     description: The order's status
+ *     description: The order item change's status
  *     enum:
  *       - item_add
  *       - item_remove
@@ -83,20 +83,36 @@ export class OrderItemChange extends SoftDeletableEntity {
  *     description: The ID of the order edit
  *     example: oe_01G2SG30J8C85S4A5CHM2S1NS2
  *   order_edit:
- *     description: Order edit object
+ *     description: Available if the relation `order_edit` is expanded.
  *     $ref: "#/components/schemas/order_edit"
  *   original_line_item_id:
  *      type: string
  *      description: The ID of the original line item in the order
  *      example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
  *   original_line_item:
- *      description: Original line item object.
+ *      description: Available if the relation `original_line_item` is expanded.
  *      $ref: "#/components/schemas/line_item"
  *   line_item_id:
  *      type: string
  *      description: The ID of the cloned line item.
  *      example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
  *   line_item:
- *      description: Line item object.
+ *      description: Available if the relation `line_item` is expanded.
  *      $ref: "#/components/schemas/line_item"
+ *   created_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was created."
+ *     format: date-time
+ *   updated_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was updated."
+ *     format: date-time
+ *   deleted_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was deleted."
+ *     format: date-time
+ *   metadata:
+ *     type: object
+ *     description: An optional key-value map with additional details
+ *     example: {car: "white"}
  */

packages/medusa/src/models/payment-collection.ts

@@ -111,3 +111,103 @@ export class PaymentCollection extends SoftDeletableEntity {
     this.id = generateEntityId(this.id, "paycol")
   }
 }
+
+
+/**
+ * @schema payment_collection
+ * title: "Payment Collection"
+ * description: "Payment Collection"
+ * x-resourceId: payment_collection
+ * required:
+ *   - type
+ *   - status
+ *   - amount
+ *   - region_id
+ *   - currency_code
+ *   - created_by
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The payment collection's ID
+ *     example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
+ *   type:
+ *     type: string
+ *     description: The type of the payment collection
+ *     enum:
+ *       - order_edit
+ *   status:
+ *     type: string
+ *     description: The type of the payment collection
+ *     enum:
+ *       - not_paid
+ *       - awaiting
+ *       - authorized
+ *       - partially_authorized
+ *       - captured
+ *       - partially_captured
+ *       - refunded
+ *       - partially_refunded
+ *       - canceled
+ *       - requires_action
+ *   description:
+ *     type: string
+ *     description: Description of the payment collection
+ *   amount:
+ *     type: number
+ *     description: Amount of the payment collection.
+ *   authorized_amount:
+ *     type: number
+ *     description: Authorized amount of the payment collection.
+ *   captured_amount:
+ *     type: number
+ *     description: Captured amount of the payment collection.
+ *   refunded_amount:
+ *     type: number
+ *     description: Refunded amount of the payment collection.
+ *   region_id:
+ *     type: string
+ *     description: The region's ID
+ *     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+ *   region:
+ *     description: Available if the relation `region` is expanded.
+ *     $ref: "#/components/schemas/region"
+ *   currency_code:
+ *     description: "The 3 character ISO code for the currency."
+ *     type: string
+ *     example: usd
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *       description: See a list of codes.
+ *   currency:
+ *     description: Available if the relation `currency` is expanded.
+ *     $ref: "#/components/schemas/currency"
+ *   payment_sessions:
+ *     type: array
+ *     description: Available if the relation `payment_sessions` is expanded.
+ *     items:
+ *       $ref: "#/components/schemas/payment_session"
+ *   payments:
+ *     type: array
+ *     description: Available if the relation `payments` is expanded.
+ *     items:
+ *       $ref: "#/components/schemas/payment"
+ *   created_by:
+ *     type: string
+ *     description: "The ID of the user that created the payment collection."
+ *   created_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was created."
+ *     format: date-time
+ *   updated_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was updated."
+ *     format: date-time
+ *   deleted_at:
+ *     type: string
+ *     description: "The date with timezone at which the resource was deleted."
+ *     format: date-time
+ *   metadata:
+ *     type: object
+ *     description: An optional key-value map with additional details
+ *     example: {car: "white"}
+ */

packages/medusa/src/models/region.ts

@@ -118,7 +118,7 @@ export class Region extends SoftDeletableEntity {
  * properties:
  *   id:
  *     type: string
- *     description: The cart's ID
+ *     description: The region's ID
  *     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
  *   name:
  *     description: "The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name."