From 884322447e0032fd627caff1637aa93fb5a88cbf Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Wed, 9 Nov 2022 18:24:48 +0200
Subject: [PATCH] docs: fixes to the API reference (#2570)

---
 .../admin/currencies/list-currencies.ts       |  40 ++++---
 .../admin/currencies/update-currency.ts       |  22 ++++
 .../routes/admin/order-edits/add-line-item.ts |  33 ++++--
 .../admin/order-edits/cancel-order-edit.ts    |   4 +-
 .../admin/order-edits/confirm-order-edit.ts   |   4 +-
 .../admin/order-edits/create-order-edit.ts    |  20 +++-
 .../delete-order-edit-item-change.ts          |   2 +-
 .../admin/order-edits/delete-order-edit.ts    |   2 +-
 .../admin/order-edits/get-order-edit.ts       |   2 +-
 .../admin/order-edits/list-order-edit.ts      |  15 ++-
 .../admin/order-edits/request-confirmation.ts |   2 +-
 .../update-order-edit-line-item.ts            |  19 +++-
 .../admin/order-edits/update-order-edit.ts    |  15 ++-
 .../routes/admin/returns/receive-return.ts    |   4 +-
 .../store/order-edits/complete-order-edit.ts  |   2 +-
 .../store/order-edits/decline-order-edit.ts   |   2 +-
 .../store/order-edits/get-order-edit.ts       |   2 +-
 .../routes/store/products/list-products.ts    |   9 ++
 .../api/routes/store/returns/create-return.ts |   4 +-
 packages/medusa/src/models/order-edit.ts      |  30 +++++-
 .../medusa/src/models/order-item-change.ts    |  24 ++++-
 .../medusa/src/models/payment-collection.ts   | 100 ++++++++++++++++++
 packages/medusa/src/models/region.ts          |   2 +-
 23 files changed, 306 insertions(+), 53 deletions(-)

diff --git a/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts b/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts
index ecdc325591..e7698e2078 100644
--- a/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts
+++ b/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts
@@ -15,9 +15,25 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  * parameters:
  *   - (query) code {string} Code of the currency to search for.
  *   - (query) includes_tax {boolean} Search for tax inclusive currencies.
- *   - (query) order {string} to retrieve products in.
- *   - (query) offset {string} How many products to skip in the result.
- *   - (query) limit {string} Limit the number of products returned.
+ *   - (query) order {string} order to retrieve products in.
+ *   - (query) offset=0 {number} How many products to skip in the result.
+ *   - (query) limit=20 {number} Limit the number of products returned.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.currencies.list()
+ *       .then(({ currencies, count, offset, limit }) => {
+ *         console.log(currencies.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/currencies' \
+ *       --header 'Authorization: Bearer {api_token}'
  * tags:
  *   - Currency
  * responses:
@@ -27,19 +43,19 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  *       application/json:
  *         schema:
  *           properties:
- *             count:
- *               description: The number of Currency.
- *               type: integer
- *             offset:
- *               description: The offset of the Currency query.
- *               type: integer
- *             limit:
- *               description: The limit of the currency query.
- *               type: integer
  *             currencies:
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/currency"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req: ExtendedRequest<Currency>, res) => {
   const currencyService: CurrencyService = req.scope.resolve("currencyService")
diff --git a/packages/medusa/src/api/routes/admin/currencies/update-currency.ts b/packages/medusa/src/api/routes/admin/currencies/update-currency.ts
index 27b3fc11bb..90668c4482 100644
--- a/packages/medusa/src/api/routes/admin/currencies/update-currency.ts
+++ b/packages/medusa/src/api/routes/admin/currencies/update-currency.ts
@@ -21,6 +21,28 @@ import TaxInclusivePricingFeatureFlag from "../../../../loaders/feature-flags/ta
  *           includes_tax:
  *             type: boolean
  *             description: "[EXPERIMENTAL] Tax included in prices of currency."
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.currencies.update(code, {
+ *         includes_tax: true
+ *       })
+ *       .then(({ currency }) => {
+ *         console.log(currency.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/currencies/{code}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "includes_tax": true
+ *       }'
  * tags:
  *   - Currency
  * responses:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
index f33e89adce..07af8e9f17 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
@@ -15,6 +15,23 @@ import {
  * description: "Create an OrderEdit LineItem."
  * parameters:
  *   - (path) id=* {string} The ID of the Order Edit.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - variant_id
+ *           - quantity
+ *         properties:
+ *           variant_id:
+ *             description: The ID of the variant ID to add
+ *             type: string
+ *           quantity:
+ *             description: The quantity to add
+ *             type: number
+ *           metadata:
+ *             description: An optional set of key-value pairs to hold additional information.
+ *             type: object
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: JavaScript
@@ -23,16 +40,20 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdit.addLineItem(order_edit_id, { variant_id, quantity })
- *        .then(({ order_edit }) => {
- *           console.log(order_edit.id)
- *        })
+ *       medusa.admin.orderEdits.addLineItem(order_edit_id, {
+ *         variant_id, 
+ *         quantity 
+ *       })
+ *       .then(({ order_edit }) => {
+ *          console.log(order_edit.id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
  *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items' \
- *       --header 'Authorization: Bearer {api_token}'
- *       -d '{ "variant_id": "some_variant_id", "quantity": 3 }'
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", "quantity": 3 }'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
diff --git a/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts
index 4e85e887b8..9bbed396ab 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts
@@ -21,14 +21,14 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdit.cancel(orderEditId)
+ *       medusa.admin.orderEdits.cancel(order_edit_id)
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/:id/cancel' \
+ *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \
  *       --header 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
diff --git a/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts
index b477e6b873..b6e840a10c 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts
@@ -21,14 +21,14 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdit.confirm(orderEditId)
+ *       medusa.admin.orderEdits.confirm(order_edit_id)
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/:id/confirm' \
+ *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \
  *       --header 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
diff --git a/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts
index 6fdcf3b0ac..bdb9b1103d 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts
@@ -12,6 +12,19 @@ import {
  * operationId: "PostOrderEdits"
  * summary: "Create an OrderEdit"
  * description: "Creates an OrderEdit."
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - order_id
+ *         properties:
+ *           order_id:
+ *             description: The ID of the order to create the edit for.
+ *             type: string
+ *           internal_note:
+ *             description: An optional note to create for the order edit.
+ *             type: string
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: JavaScript
@@ -20,7 +33,7 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdit.create({ order_id, internal_note })
+ *       medusa.admin.orderEdits.create({ order_id })
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
@@ -28,8 +41,9 @@ import {
  *     label: cURL
  *     source: |
  *       curl --location --request POST 'https://medusa-url.com/admin/order-edits' \
- *       --header 'Authorization: Bearer {api_token}'
- *       -d '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }'
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
index 4f69732676..3c0735f80e 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
@@ -17,7 +17,7 @@ import { OrderEditService } from "../../../../services"
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdits.deleteItemChange(item_change_id, order_edit_id)
+ *       medusa.admin.orderEdits.deleteItemChange(order_edit_id, item_change_id)
  *         .then(({ id, object, deleted }) => {
  *           console.log(id)
  *         })
diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
index 8ee7cc85bd..f1a993e2e5 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
@@ -16,7 +16,7 @@ import { OrderEditService } from "../../../../services"
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdits.delete(edit_id)
+ *       medusa.admin.orderEdits.delete(order_edit_id)
  *         .then(({ id, object, deleted }) => {
  *           console.log(id)
  *         })
diff --git a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
index cb48a7ab51..23a59f0f69 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
@@ -19,7 +19,7 @@ import { FindParams } from "../../../../types/common"
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdit.retrieve(orderEditId)
+ *       medusa.admin.orderEdits.retrieve(orderEditId)
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
diff --git a/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts
index 26756244b5..81841fee4c 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts
@@ -23,9 +23,9 @@ import { IsOptional, IsString } from "class-validator"
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdit.list()
- *         .then(({ order_edits }) => {
- *           console.log(order_edits)
+ *       medusa.admin.orderEdits.list()
+ *         .then(({ order_edits, count, limit, offset }) => {
+ *           console.log(order_edits.length)
  *         })
  *   - lang: Shell
  *     label: cURL
@@ -47,6 +47,15 @@ import { IsOptional, IsString } from "class-validator"
  *             order_edits:
  *               type: array
  *               $ref: "#/components/schemas/order_edit"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
index 6ff9e46e3e..19f747ec84 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
@@ -20,7 +20,7 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdits.requestConfirmation(edit_id)
+ *       medusa.admin.orderEdits.requestConfirmation(order_edit_id)
  *         .then({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
index 5b7fbb3de9..2d31061634 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
@@ -16,6 +16,16 @@ import {
  * parameters:
  *   - (path) id=* {string} The ID of the Order Edit to update.
  *   - (path) item_id=* {string} The ID of the order edit item to update.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - quantity
+ *         properties:
+ *           quantity:
+ *             description: The quantity to update
+ *             type: number
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -23,7 +33,9 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.orderEdits.updateLineItem(order_edit_id, line_item_id)
+ *       medusa.admin.orderEdits.updateLineItem(order_edit_id, line_item_id, {
+ *           quantity: 5
+ *         })
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
@@ -31,8 +43,9 @@ import {
  *     label: cURL
  *     source: |
  *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \
- *       --header 'Authorization: Bearer {api_token}'
- *       -d '{ "quantity": 5 }'
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{ "quantity": 5 }'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
index c12bb65cb2..7c9da4e78f 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
@@ -16,6 +16,14 @@ import {
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the OrderEdit.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         properties:
+ *           internal_note:
+ *             description: An optional note to create or update for the order edit.
+ *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -23,8 +31,9 @@ import {
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       const params = {internal_note: "internal reason XY"}
- *       medusa.admin.orderEdit.update(orderEditId, params)
+ *       medusa.admin.orderEdits.update(order_edit_id, {
+ *         internal_note: "internal reason XY"
+ *       })
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
@@ -32,7 +41,7 @@ import {
  *     label: cURL
  *     source: |
  *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       --header 'Authorization: Bearer {api_token}' \
  *       --header 'Content-Type: application/json' \
  *       --data-raw '{
  *           "internal_note": "internal reason XY"
diff --git a/packages/medusa/src/api/routes/admin/returns/receive-return.ts b/packages/medusa/src/api/routes/admin/returns/receive-return.ts
index 9a9b1690a3..0b7d3bd0a6 100644
--- a/packages/medusa/src/api/routes/admin/returns/receive-return.ts
+++ b/packages/medusa/src/api/routes/admin/returns/receive-return.ts
@@ -58,8 +58,8 @@ import { isDefined } from "../../../../utils"
  *           }
  *         ]
  *       })
- *       .then(({ return }) => {
- *         console.log(return.id);
+ *       .then((data) => {
+ *         console.log(data.return.id);
  *       });
  *   - lang: Shell
  *     label: cURL
diff --git a/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts b/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts
index 45d4293e8c..ed467bb35f 100644
--- a/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts
@@ -21,7 +21,7 @@ import { MedusaError } from "medusa-core-utils"
  *     source: |
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       medusa.orderEdit.complete(orderEditId)
+ *       medusa.orderEdits.complete(order_edit_id)
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
diff --git a/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts b/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts
index d9d07b6874..fd320f7574 100644
--- a/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts
@@ -28,7 +28,7 @@ import {
  *     source: |
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       medusa.orderEdit.decline(orderEditId)
+ *       medusa.orderEdits.decline(order_edit_id)
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id);
  *         })
diff --git a/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts b/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts
index 887a8dc977..ee537c517f 100644
--- a/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts
@@ -14,7 +14,7 @@ import { OrderEditService } from "../../../../services"
  *     source: |
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       medusa.orderEdit.retrieve(orderEditId)
+ *       medusa.orderEdits.retrieve(order_edit_id)
  *       .then(({ order_edit }) => {
  *         console.log(order_edit.id);
  *       });
diff --git a/packages/medusa/src/api/routes/store/products/list-products.ts b/packages/medusa/src/api/routes/store/products/list-products.ts
index f51eacc632..339487dcd6 100644
--- a/packages/medusa/src/api/routes/store/products/list-products.ts
+++ b/packages/medusa/src/api/routes/store/products/list-products.ts
@@ -45,6 +45,15 @@ import { IsType } from "../../../../utils/validators/is-type"
  *           items:
  *             type: string
  *   - in: query
+ *     name: sales_channel_id
+ *     style: form
+ *     explode: false
+ *     description: an array of sales channel IDs to filter the retrieved products by.
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
+ *   - in: query
  *     name: collection_id
  *     style: form
  *     explode: false
diff --git a/packages/medusa/src/api/routes/store/returns/create-return.ts b/packages/medusa/src/api/routes/store/returns/create-return.ts
index a04b718542..6587fa9c0f 100644
--- a/packages/medusa/src/api/routes/store/returns/create-return.ts
+++ b/packages/medusa/src/api/routes/store/returns/create-return.ts
@@ -76,8 +76,8 @@ import { validator } from "../../../../utils/validator"
  *           }
  *         ]
  *       })
- *       .then(({ return }) => {
- *         console.log(return.id);
+ *       .then((data) => {
+ *         console.log(data.return.id);
  *       });
  *   - lang: Shell
  *     label: cURL
diff --git a/packages/medusa/src/models/order-edit.ts b/packages/medusa/src/models/order-edit.ts
index afa954827f..3418e1c268 100644
--- a/packages/medusa/src/models/order-edit.ts
+++ b/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
  */
diff --git a/packages/medusa/src/models/order-item-change.ts b/packages/medusa/src/models/order-item-change.ts
index 3205377922..7fd917dd25 100644
--- a/packages/medusa/src/models/order-item-change.ts
+++ b/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"}
  */
diff --git a/packages/medusa/src/models/payment-collection.ts b/packages/medusa/src/models/payment-collection.ts
index f58708a0af..a1a7778645 100644
--- a/packages/medusa/src/models/payment-collection.ts
+++ b/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"}
+ */
diff --git a/packages/medusa/src/models/region.ts b/packages/medusa/src/models/region.ts
index 16adf80be1..4004ba2ef6 100644
--- a/packages/medusa/src/models/region.ts
+++ b/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."