chore(oas): improvements to examples and descriptions (#4545)

* improve curl examples in OAS

* update tags

* fix oas errors

* update tags and their descriptions

* updated oas of endpoints

* improved oas of all admin endpoints

* improved store OAS comments

* improved models OAS comments

* small change

packages/medusa/src/api/routes/admin/apps/authorize-app.ts

@@ -7,7 +7,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/apps/authorizations
  * operationId: "PostApps"
  * summary: "Generate Token for App"
- * description: "Generates a token for an application."
+ * description: "Use an app's Oauth provider to generate and store a new token for authentication."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -20,9 +20,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/apps/authorizations' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/apps/authorizations' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "application_name": "example",
  *           "state": "ready",
@@ -74,7 +74,7 @@ export default async (req, res) => {
  * properties:
  *   application_name:
  *     type: string
- *     description:  Name of the application for the token to be generated for.
+ *     description: Name of the application for to generate the token for.
  *   state:
  *     type: string
  *     description: State of the application.

packages/medusa/src/api/routes/admin/apps/index.ts

@@ -23,6 +23,7 @@ export default (app) => {
  *   - apps
  * properties:
  *   apps:
+ *     description: App details.
  *     $ref: "#/components/schemas/OAuth"
  */
 export type AdminAppsRes = {
@@ -37,6 +38,7 @@ export type AdminAppsRes = {
  * properties:
  *   apps:
  *      type: array
+ *      description: An array of app details.
  *      items:
  *        $ref: "#/components/schemas/OAuth"
  */

packages/medusa/src/api/routes/admin/apps/list.ts

@@ -4,7 +4,7 @@ import { OauthService } from "../../../../services"
  * @oas [get] /admin/apps
  * operationId: "GetApps"
  * summary: "List Applications"
- * description: "Retrieve a list of applications."
+ * description: "Retrieve a list of applications registered in the Medusa backend."
  * x-authenticated: true
  * x-codegen:
  *   method: list
@@ -12,8 +12,8 @@ import { OauthService } from "../../../../services"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/apps' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/apps' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/auth/create-session.ts

@@ -12,10 +12,8 @@ import { validator } from "../../../../utils/validator"
  * operationId: "PostAuth"
  * summary: "User Login"
  * x-authenticated: false
- * description: "Logs a User in and authorizes them to manage Store settings."
- * parameters:
- *   - (body) email=* {string} The User's email.
- *   - (body) password=* {string} The User's password.
+ * description: "Log a User in and includes the Cookie session in the response header. The cookie session can be used in subsequent requests to authorize the user to perform admin functionalities.
+ * When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests."
  * requestBody:
  *   content:
  *     application/json:
@@ -30,8 +28,8 @@ import { validator } from "../../../../utils/validator"
  *       import Medusa from "@medusajs/medusa-js"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       medusa.admin.auth.createSession({
- *         email: 'user@example.com',
- *         password: 'supersecret'
+ *         email: "user@example.com",
+ *         password: "supersecret"
  *       })
  *       .then(({ user }) => {
  *         console.log(user.id);
@@ -39,8 +37,8 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/auth' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/auth' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *         "email": "user@example.com",
  *         "password": "supersecret"
@@ -110,11 +108,11 @@ export default async (req, res) => {
  * properties:
  *   email:
  *     type: string
- *     description: The User's email.
+ *     description: The user's email.
  *     format: email
  *   password:
  *     type: string
- *     description: The User's password.
+ *     description: The user's password.
  *     format: password
  */
 export class AdminPostAuthReq {

packages/medusa/src/api/routes/admin/auth/delete-session.ts

@@ -3,7 +3,8 @@
  * operationId: "DeleteAuth"
  * summary: "User Logout"
  * x-authenticated: true
- * description: "Deletes the current session for the logged in user."
+ * description: "Delete the current session for the logged in user. This will only work if you're using Cookie session for authentication. If the API token is still passed in the header,
+ * the user is still authorized to perform admin functionalities in other endpoints."
  * x-codegen:
  *   method: deleteSession
  * x-codeSamples:
@@ -12,13 +13,13 @@
  *     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
+ *       // must be previously logged in
  *       medusa.admin.auth.deleteSession()
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/auth' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/auth' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/auth/get-session.ts

@@ -6,7 +6,7 @@ import _ from "lodash"
  * operationId: "GetAuth"
  * summary: "Get Current User"
  * x-authenticated: true
- * description: "Gets the currently logged in User."
+ * description: "Get the currently logged in user's details."
  * x-codegen:
  *   method: getSession
  * x-codeSamples:
@@ -23,8 +23,8 @@ import _ from "lodash"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/auth' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/auth' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/auth/index.ts

@@ -30,6 +30,7 @@ export default (app) => {
  *   - user
  * properties:
  *   user:
+ *     description: User details.
  *     $ref: "#/components/schemas/User"
  */
 export type AdminAuthRes = {

packages/medusa/src/api/routes/admin/batch/cancel-batch-job.ts

@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/batch-jobs/{id}/cancel
  * operationId: "PostBatchJobsBatchJobCancel"
  * summary: "Cancel a Batch Job"
- * description: "Marks a batch job as canceled"
+ * description: "Mark a batch job as canceled. When a batch job is canceled, the processing of the batch job doesn’t automatically stop."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the batch job.
@@ -18,15 +18,15 @@ import { EntityManager } from "typeorm"
  *       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.batchJobs.cancel(batch_job_id)
+ *       medusa.admin.batchJobs.cancel(batchJobId)
  *       .then(({ batch_job }) => {
  *         console.log(batch_job.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts

@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/batch-jobs/{id}/confirm
  * operationId: "PostBatchJobsBatchJobConfirmProcessing"
  * summary: "Confirm a Batch Job"
- * description: "Confirms that a previously requested batch job should be executed."
+ * description: "When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This endpoint confirms that the batch job should be executed."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the batch job.
@@ -18,15 +18,15 @@ import { EntityManager } from "typeorm"
  *       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.batchJobs.confirm(batch_job_id)
+ *       medusa.admin.batchJobs.confirm(batchJobId)
  *       .then(({ batch_job }) => {
  *         console.log(batch_job.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/batch/create-batch-job.ts

@@ -9,7 +9,11 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/batch-jobs
  * operationId: "PostBatchJobs"
  * summary: "Create a Batch Job"
- * description: "Creates a Batch Job."
+ * description: "Create a Batch Job to be executed asynchronously in the Medusa backend. If `dry_run` is set to `true`, the batch job will not be executed until the it is confirmed,
+ *  which can be done using the Confirm Batch Job endpoint."
+ * externalDocs:
+ *   description: "How to create a batch job"
+ *   url: "https://docs.medusajs.com/development/batch-jobs/create#create-batch-job"
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -35,9 +39,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/batch-jobs' \
- *       --header 'Content-Type: application/json' \
- *       --header 'Authorization: Bearer {api_token}' \
+ *       curl -X POST 'https://medusa-url.com/admin/batch-jobs' \
+ *       -H 'Content-Type: application/json' \
+ *       -H 'Authorization: Bearer {api_token}' \
  *       --data-raw '{
  *           "type": "product-export",
  *           "context": { }
@@ -97,7 +101,7 @@ export default async (req, res) => {
  * properties:
  *   type:
  *     type: string
- *     description: The type of batch job to start.
+ *     description: The type of batch job to start, which is defined by the `batchType` property of the associated batch job strategy.
  *     example: product-export
  *   context:
  *     type: object
@@ -120,7 +124,7 @@ export default async (req, res) => {
  *           - images
  *   dry_run:
  *     type: boolean
- *     description: Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.
+ *     description: Set a batch job in dry_run mode, which would delay executing the batch job until it's confirmed.
  *     default: false
  */
 export class AdminPostBatchesReq {

packages/medusa/src/api/routes/admin/batch/get-batch-job.ts

@@ -2,7 +2,7 @@
  * @oas [get] /admin/batch-jobs/{id}
  * operationId: "GetBatchJobsBatchJob"
  * summary: "Get a Batch Job"
- * description: "Retrieves a Batch Job."
+ * description: "Retrieve the details of a batch job."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Batch Job
@@ -15,15 +15,15 @@
  *       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.batchJobs.retrieve(batch_job_id)
+ *       medusa.admin.batchJobs.retrieve(batchJobId)
  *       .then(({ batch_job }) => {
  *         console.log(batch_job.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/batch-jobs/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/batch-jobs/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/batch/index.ts

@@ -49,6 +49,7 @@ export default (app) => {
  *   - batch_job
  * properties:
  *   batch_job:
+ *     description: Batch job details.
  *     $ref: "#/components/schemas/BatchJob"
  */
 export type AdminBatchJobRes = {
@@ -66,6 +67,7 @@ export type AdminBatchJobRes = {
  * properties:
  *   batch_jobs:
  *      type: array
+ *      description: An array of batch job details.
  *      items:
  *        $ref: "#/components/schemas/BatchJob"
  *   count:
@@ -73,7 +75,7 @@ export type AdminBatchJobRes = {
  *      description: The total number of items available
  *   offset:
  *      type: integer
- *      description: The number of items skipped before these items
+ *      description: The number of batch jobs skipped when retrieving the batch jobs.
  *   limit:
  *      type: integer
  *      description: The number of items per page

packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts

@@ -12,11 +12,11 @@ import { isDefined } from "medusa-core-utils"
  * @oas [get] /admin/batch-jobs
  * operationId: "GetBatchJobs"
  * summary: "List Batch Jobs"
- * description: "Retrieve a list of Batch Jobs."
+ * description: "Retrieve a list of Batch Jobs. The batch jobs can be filtered by fields such as `type` or `confirmed_at`. The batch jobs can also be sorted or paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) limit=10 {integer} The number of batch jobs to return.
- *   - (query) offset=0 {integer} The number of batch jobs to skip before results.
+ *   - (query) limit=10 {integer} Limit the number of batch jobs returned.
+ *   - (query) offset=0 {integer} The number of batch jobs to skip when retrieving the batch jobs.
  *   - in: query
  *     name: id
  *     style: form
@@ -43,7 +43,7 @@ import { isDefined } from "medusa-core-utils"
  *     name: confirmed_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc.
+ *     description: Filter by a confirmation date range.
  *     schema:
  *       type: object
  *       properties:
@@ -67,7 +67,7 @@ import { isDefined } from "medusa-core-utils"
  *     name: pre_processed_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc.
+ *     description: Filter by a pre-processing date range.
  *     schema:
  *       type: object
  *       properties:
@@ -91,7 +91,7 @@ import { isDefined } from "medusa-core-utils"
  *     name: completed_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was completed, i.e. less than, greater than etc.
+ *     description: Filter by a completion date range.
  *     schema:
  *       type: object
  *       properties:
@@ -115,7 +115,7 @@ import { isDefined } from "medusa-core-utils"
  *     name: failed_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was failed, i.e. less than, greater than etc.
+ *     description: Filter by a failure date range.
  *     schema:
  *       type: object
  *       properties:
@@ -139,7 +139,7 @@ import { isDefined } from "medusa-core-utils"
  *     name: canceled_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was canceled, i.e. less than, greater than etc.
+ *     description: Filter by a cancelation date range.
  *     schema:
  *       type: object
  *       properties:
@@ -159,14 +159,14 @@ import { isDefined } from "medusa-core-utils"
  *            type: string
  *            description: filter by dates greater than or equal to this date
  *            format: date
- *   - (query) order {string} Field used to order retrieved batch jobs
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each order of the result.
- *   - (query) fields {string} (Comma separated) Which fields should be included in each order of the result.
+ *   - (query) order {string} A batch-job field to sort-order the retrieved batch jobs by.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned batch jobs.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned batch jobs.
  *   - in: query
  *     name: created_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was created, i.e. less than, greater than etc.
+ *     description: Filter by a creation date range.
  *     schema:
  *       type: object
  *       properties:
@@ -190,7 +190,7 @@ import { isDefined } from "medusa-core-utils"
  *     name: updated_at
  *     style: form
  *     explode: false
- *     description: Date comparison for when resulting collections was updated, i.e. less than, greater than etc.
+ *     description: Filter by an update date range.
  *     schema:
  *       type: object
  *       properties:
@@ -222,13 +222,13 @@ import { isDefined } from "medusa-core-utils"
  *       // must be previously logged in or use api token
  *       medusa.admin.batchJobs.list()
  *       .then(({ batch_jobs, limit, offset, count }) => {
- *         console.log(batch_jobs.length);
- *       });
+ *         console.log(batch_jobs.length)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/batch-jobs' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/batch-jobs' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/collections/add-products.ts

@@ -8,11 +8,11 @@ import { defaultAdminCollectionsRelations } from "./index"
 /**
  * @oas [post] /admin/collections/{id}/products/batch
  * operationId: "PostProductsToCollection"
- * summary: "Update Products"
- * description: "Updates products associated with a Product Collection"
+ * summary: "Add Products to Collection"
+ * description: "Add products to a product collection."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The ID of the Collection.
+ *   - (path) id=* {string} The ID of the product collection.
  * requestBody:
  *   content:
  *     application/json:
@@ -21,12 +21,27 @@ import { defaultAdminCollectionsRelations } from "./index"
  * x-codegen:
  *   method: addProducts
  * 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.collections.addProducts(collectionId, {
+ *         product_ids: [
+ *           productId1,
+ *           productId2
+ *         ]
+ *       })
+ *       .then(({ collection }) => {
+ *         console.log(collection.products)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "product_ids": [
  *               "prod_01G1G5V2MBA328390B5AXJ610F"
@@ -36,7 +51,7 @@ import { defaultAdminCollectionsRelations } from "./index"
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK

packages/medusa/src/api/routes/admin/collections/create-collection.ts

@@ -8,7 +8,7 @@ import { defaultAdminCollectionsRelations } from "."
  * @oas [post] /admin/collections
  * operationId: "PostCollections"
  * summary: "Create a Collection"
- * description: "Creates a Product Collection."
+ * description: "Create a Product Collection."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -25,7 +25,7 @@ import { defaultAdminCollectionsRelations } from "."
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.collections.create({
- *         title: 'New Collection'
+ *         title: "New Collection"
  *       })
  *       .then(({ collection }) => {
  *         console.log(collection.id);
@@ -33,9 +33,9 @@ import { defaultAdminCollectionsRelations } from "."
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/collections' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/collections' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "title": "New Collection"
  *       }'
@@ -43,7 +43,7 @@ import { defaultAdminCollectionsRelations } from "."
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK
@@ -93,10 +93,10 @@ export default async (req: Request, res: Response) => {
  * properties:
  *   title:
  *     type: string
- *     description:  The title to identify the Collection by.
+ *     description: The title of the collection.
  *   handle:
  *     type: string
- *     description:  An optional handle to be used in slugs, if none is provided we will kebab-case the title.
+ *     description: An optional handle to be used in slugs. If none is provided, the kebab-case version of the title will be used.
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.
  *     type: object

packages/medusa/src/api/routes/admin/collections/delete-collection.ts

@@ -7,7 +7,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  * @oas [delete] /admin/collections/{id}
  * operationId: "DeleteCollectionsCollection"
  * summary: "Delete a Collection"
- * description: "Deletes a Product Collection."
+ * description: "Delete a Product Collection. This does not delete associated products."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Collection.
@@ -20,20 +20,20 @@ import ProductCollectionService from "../../../../services/product-collection"
  *       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.collections.delete(collection_id)
+ *       medusa.admin.collections.delete(collectionId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/collections/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK

packages/medusa/src/api/routes/admin/collections/get-collection.ts

@@ -7,7 +7,7 @@ import { defaultAdminCollectionsRelations } from "."
  * @oas [get] /admin/collections/{id}
  * operationId: "GetCollectionsCollection"
  * summary: "Get a Collection"
- * description: "Retrieves a Product Collection."
+ * description: "Retrieve a Product Collection by its ID. The products associated with it are expanded and returned as well."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Product Collection
@@ -20,20 +20,20 @@ import { defaultAdminCollectionsRelations } from "."
  *       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.collections.retrieve(collection_id)
+ *       medusa.admin.collections.retrieve(collectionId)
  *       .then(({ collection }) => {
  *         console.log(collection.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/collections/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/collections/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK

packages/medusa/src/api/routes/admin/collections/index.ts

@@ -80,6 +80,7 @@ export const defaultAdminCollectionsRelations = ["products.profiles"]
  * properties:
  *   collections:
  *      type: array
+ *      description: an array of collection details
  *      items:
  *        $ref: "#/components/schemas/ProductCollection"
  *   count:
@@ -87,7 +88,7 @@ export const defaultAdminCollectionsRelations = ["products.profiles"]
  *      description: The total number of items available
  *   offset:
  *      type: integer
- *      description: The number of items skipped before these items
+ *      description: The number of product collections skipped when retrieving the product collections.
  *   limit:
  *      type: integer
  *      description: The number of items per page
@@ -137,7 +138,7 @@ export type AdminCollectionsDeleteRes = DeleteResponse
  *     description: "The IDs of the products removed from the collection"
  *     type: array
  *     items:
- *       description: "The ID of a Product to add to the Product Collection."
+ *       description: "The ID of the Product removed from the Product Collection."
  *       type: string
  */
 export type AdminDeleteProductsFromCollectionRes = {
@@ -157,6 +158,7 @@ export type AdminDeleteProductsFromCollectionRes = {
  *   - collection
  * properties:
  *   collection:
+ *     type: "Product Collection details."
  *     $ref: "#/components/schemas/ProductCollection"
  */
 export type AdminCollectionsRes = {

packages/medusa/src/api/routes/admin/collections/list-collections.ts

@@ -9,18 +9,18 @@ import { Type } from "class-transformer"
  * @oas [get] /admin/collections
  * operationId: "GetCollections"
  * summary: "List Collections"
- * description: "Retrieve a list of Product Collection."
+ * description: "Retrieve a list of Product Collection. The product collections can be filtered by fields such as `handle` or `title`. The collections can also be sorted or paginated."
  * x-authenticated: true
  * parameters:
  *   - (query) limit=10 {integer} The number of collections to return.
- *   - (query) offset=0 {integer} The number of collections to skip before the results.
- *   - (query) title {string} The title of collections to return.
- *   - (query) handle {string} The handle of collections to return.
- *   - (query) q {string} a search term to search titles and handles.
- *   - (query) discount_condition_id {string} The discount condition id on which to filter the product collections.
+ *   - (query) offset=0 {integer} The number of collections to skip when retrieving the collections.
+ *   - (query) title {string} Filter collections by their title.
+ *   - (query) handle {string} Filter collections by their handle.
+ *   - (query) q {string} a term to search collections by their title or handle.
+ *   - (query) discount_condition_id {string} Filter collections by a discount condition ID associated with them.
  *   - in: query
  *     name: created_at
- *     description: Date comparison for when resulting collections were created.
+ *     description: Filter by a creation date range.
  *     schema:
  *       type: object
  *       properties:
@@ -42,7 +42,7 @@ import { Type } from "class-transformer"
  *            format: date
  *   - in: query
  *     name: updated_at
- *     description: Date comparison for when resulting collections were updated.
+ *     description: Filter by an update date range.
  *     schema:
  *       type: object
  *       properties:
@@ -64,7 +64,7 @@ import { Type } from "class-transformer"
  *            format: date
  *   - in: query
  *     name: deleted_at
- *     description: Date comparison for when resulting collections were deleted.
+ *     description: Filter by a deletion date range.
  *     schema:
  *       type: object
  *       properties:
@@ -101,13 +101,13 @@ import { Type } from "class-transformer"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/collections' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/collections' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK

packages/medusa/src/api/routes/admin/collections/remove-products.ts

@@ -7,11 +7,11 @@ import ProductCollectionService from "../../../../services/product-collection"
 /**
  * @oas [delete] /admin/collections/{id}/products/batch
  * operationId: "DeleteProductsFromCollection"
- * summary: "Remove Product"
- * description: "Removes products associated with a Product Collection"
+ * summary: "Remove Products from Collection"
+ * description: "Remove a list of products from a collection. This would not delete the product, only the association between the product and the collection."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The ID of the Collection.
+ *   - (path) id=* {string} The ID of the Product Collection.
  * requestBody:
  *   content:
  *     application/json:
@@ -20,12 +20,27 @@ import ProductCollectionService from "../../../../services/product-collection"
  * x-codegen:
  *   method: removeProducts
  * 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.collections.removeProducts(collectionId, {
+ *         product_ids: [
+ *           productId1,
+ *           productId2
+ *         ]
+ *       })
+ *       .then(({ id, object, removed_products }) => {
+ *         console.log(removed_products)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "product_ids": [
  *               "prod_01G1G5V2MBA328390B5AXJ610F"
@@ -35,7 +50,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK

packages/medusa/src/api/routes/admin/collections/update-collection.ts

@@ -8,7 +8,7 @@ import { defaultAdminCollectionsRelations } from "."
  * @oas [post] /admin/collections/{id}
  * operationId: "PostCollectionsCollection"
  * summary: "Update a Collection"
- * description: "Updates a Product Collection."
+ * description: "Update a Product Collection's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Collection.
@@ -26,8 +26,8 @@ import { defaultAdminCollectionsRelations } from "."
  *       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.collections.update(collection_id, {
- *         title: 'New Collection'
+ *       medusa.admin.collections.update(collectionId, {
+ *         title: "New Collection"
  *       })
  *       .then(({ collection }) => {
  *         console.log(collection.id);
@@ -35,9 +35,9 @@ import { defaultAdminCollectionsRelations } from "."
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/collections/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/collections/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "title": "New Collection"
  *       }'
@@ -45,7 +45,7 @@ import { defaultAdminCollectionsRelations } from "."
  *   - api_token: []
  *   - cookie_auth: []
  * tags:
- *   - Collections
+ *   - Product Collections
  * responses:
  *  "200":
  *    description: OK
@@ -96,10 +96,10 @@ export default async (req: Request, res: Response) => {
  * properties:
  *   title:
  *     type: string
- *     description:  The title to identify the Collection by.
+ *     description: The title of the collection.
  *   handle:
  *     type: string
- *     description:  An optional handle to be used in slugs, if none is provided we will kebab-case the title.
+ *     description: An optional handle to be used in slugs. If none is provided, the kebab-case version of the title will be used.
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.
  *     type: object

packages/medusa/src/api/routes/admin/currencies/index.ts

@@ -43,6 +43,7 @@ export default (app) => {
  * properties:
  *   currencies:
  *     type: array
+ *     description: An array of currency details.
  *     items:
  *       $ref: "#/components/schemas/Currency"
  *   count:
@@ -50,7 +51,7 @@ export default (app) => {
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of currencies skipped when retrieving the currencies.
  *   limit:
  *     type: integer
  *     description: The number of items per page
@@ -66,7 +67,8 @@ export type AdminCurrenciesListRes = PaginatedResponse & {
  *   - currency
  * properties:
  *   currency:
- *       $ref: "#/components/schemas/Currency"
+ *     description: Currency details.
+ *     $ref: "#/components/schemas/Currency"
  */
 export type AdminCurrenciesRes = {
   currency: Currency

packages/medusa/src/api/routes/admin/currencies/list-currencies.ts

@@ -10,14 +10,19 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  * @oas [get] /admin/currencies
  * operationId: "GetCurrencies"
  * summary: "List Currency"
- * description: "Retrieves a list of Currency"
+ * description: "Retrieve a list of currencies. The currencies can be filtered by fields such as `code`. The currencies can also be sorted or paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) code {string} Code of the currency to search for.
- *   - (query) includes_tax {boolean} Search for tax inclusive currencies.
- *   - (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.
+ *   - (query) code {string} filter by currency code.
+ *   - in: query
+ *     name: includes_tax
+ *     description: filter currencies by whether they include taxes or not.
+ *     schema:
+ *       type: boolean
+ *       x-featureFlag: "tax_inclusive_pricing"
+ *   - (query) order {string} A field to sort order the retrieved currencies by.
+ *   - (query) offset=0 {number} The number of currencies to skip when retrieving the currencies.
+ *   - (query) limit=20 {number} The number of currencies to return.
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetCurrenciesParams
@@ -35,8 +40,8 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/currencies' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/currencies' \
+ *       -H 'Authorization: Bearer {api_token}'
  * tags:
  *   - Currencies
  * responses:

packages/medusa/src/api/routes/admin/currencies/update-currency.ts

@@ -10,7 +10,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/currencies/{code}
  * operationId: "PostCurrenciesCurrency"
  * summary: "Update a Currency"
- * description: "Update a Currency"
+ * description: "Update a Currency's details."
  * x-authenticated: true
  * parameters:
  *   - (path) code=* {string} The code of the Currency.
@@ -37,9 +37,9 @@ import { EntityManager } from "typeorm"
  *   - 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' \
+ *       curl -X POST 'https://medusa-url.com/admin/currencies/{code}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "includes_tax": true
  *       }'
@@ -74,7 +74,8 @@ export default async (req: ExtendedRequest<Currency>, res) => {
  * properties:
  *   includes_tax:
  *     type: boolean
- *     description: "[EXPERIMENTAL] Tax included in prices of currency."
+ *     x-featureFlag: "tax_inclusive_pricing"
+ *     description: "Tax included in prices of currency."
  */
 export class AdminPostCurrenciesCurrencyReq {
   @FeatureFlagDecorators(TaxInclusivePricingFeatureFlag.key, [

packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts

@@ -10,8 +10,8 @@ import { validator } from "../../../../utils/validator"
 /**
  * @oas [post] /admin/customer-groups/{id}/customers/batch
  * operationId: "PostCustomerGroupsGroupCustomersBatch"
- * summary: "Add Customers"
- * description: "Adds a list of customers, represented by id's, to a customer group."
+ * summary: "Add Customers to Group"
+ * description: "Add a list of customers to a customer group."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the customer group.
@@ -29,10 +29,10 @@ import { validator } from "../../../../utils/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.customerGroups.addCustomers(customer_group_id, {
+ *       medusa.admin.customerGroups.addCustomers(customerGroupId, {
  *         customer_ids: [
  *           {
- *             id: customer_id
+ *             id: customerId
  *           }
  *         ]
  *       })
@@ -42,9 +42,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "customer_ids": [
  *               {

packages/medusa/src/api/routes/admin/customer-groups/create-customer-group.ts

@@ -9,7 +9,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/customer-groups
  * operationId: "PostCustomerGroups"
  * summary: "Create a Customer Group"
- * description: "Creates a CustomerGroup."
+ * description: "Creates a Customer Group."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -26,7 +26,7 @@ import { validator } from "../../../../utils/validator"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.customerGroups.create({
- *         name: 'VIP'
+ *         name: "VIP"
  *       })
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
@@ -34,9 +34,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/customer-groups' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/customer-groups' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "name": "VIP"
  *       }'
@@ -96,7 +96,7 @@ export default async (req: Request, res: Response) => {
  *     description: Name of the customer group
  *   metadata:
  *     type: object
- *     description: Metadata for the customer.
+ *     description: Metadata of the customer group.
  */
 export class AdminPostCustomerGroupsReq {
   @IsString()

packages/medusa/src/api/routes/admin/customer-groups/delete-customer-group.ts

@@ -7,7 +7,7 @@ import { EntityManager } from "typeorm"
  * @oas [delete] /admin/customer-groups/{id}
  * operationId: "DeleteCustomerGroupsCustomerGroup"
  * summary: "Delete a Customer Group"
- * description: "Deletes a CustomerGroup."
+ * description: "Delete a customer group. This doesn't delete the customers associated with the customer group."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Customer Group
@@ -20,15 +20,15 @@ import { EntityManager } from "typeorm"
  *       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.customerGroups.delete(customer_group_id)
+ *       medusa.admin.customerGroups.delete(customerGroupId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts

@@ -10,8 +10,8 @@ import { validator } from "../../../../utils/validator"
 /**
  * @oas [delete] /admin/customer-groups/{id}/customers/batch
  * operationId: "DeleteCustomerGroupsGroupCustomerBatch"
- * summary: "Remove Customers"
- * description: "Removes a list of customers, represented by id's, from a customer group."
+ * summary: "Remove Customers from Group"
+ * description: "Remove a list of customers from a customer group. This doesn't delete the customer, only the association between the customer and the customer group."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the customer group.
@@ -29,10 +29,10 @@ import { validator } from "../../../../utils/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.customerGroups.removeCustomers(customer_group_id, {
+ *       medusa.admin.customerGroups.removeCustomers(customerGroupId, {
  *         customer_ids: [
  *           {
- *             id: customer_id
+ *             id: customerId
  *           }
  *         ]
  *       })
@@ -42,9 +42,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "customer_ids": [
  *               {

packages/medusa/src/api/routes/admin/customer-groups/get-customer-group-customers.ts

@@ -8,14 +8,14 @@ import { Type } from "class-transformer"
  * @oas [get] /admin/customer-groups/{id}/customers
  * operationId: "GetCustomerGroupsGroupCustomers"
  * summary: "List Customers"
- * description: "Retrieves a list of customers in a customer group"
+ * description: "Retrieve a list of customers in a customer group. The customers can be filtered by the `q` field. The customers can also be paginated."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the customer group.
- *   - (query) limit=50 {integer} The number of items to return.
- *   - (query) offset=0 {integer} The items to skip before result.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each customer.
- *   - (query) q {string} a search term to search email, first_name, and last_name.
+ *   - (query) limit=50 {integer} The number of customers to return.
+ *   - (query) offset=0 {integer} The number of customers to skip when retrieving the customers.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned customers.
+ *   - (query) q {string} a term to search customers by email, first_name, and last_name.
  * x-codegen:
  *   method: listCustomers
  *   queryParams: AdminGetGroupsGroupCustomersParams
@@ -26,15 +26,15 @@ import { Type } from "class-transformer"
  *       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.customerGroups.listCustomers(customer_group_id)
+ *       medusa.admin.customerGroups.listCustomers(customerGroupId)
  *       .then(({ customers }) => {
  *         console.log(customers.length);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}/customers' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/customer-groups/{id}/customers' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/customer-groups/get-customer-group.ts

@@ -7,12 +7,12 @@ import { FindParams } from "../../../../types/common"
  * @oas [get] /admin/customer-groups/{id}
  * operationId: "GetCustomerGroupsGroup"
  * summary: "Get a Customer Group"
- * description: "Retrieves a Customer Group."
+ * description: "Retrieve a Customer Group by its ID. You can expand the customer group's relations or select the fields that should be returned."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Customer Group.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in the customer group.
- *   - (query) fields {string} (Comma separated) Which fields should be included in the customer group.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned customer group.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned customer group.
  * x-codegen:
  *   method: retrieve
  *   queryParams: AdminGetCustomerGroupsGroupParams
@@ -23,15 +23,15 @@ 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.customerGroups.retrieve(customer_group_id)
+ *       medusa.admin.customerGroups.retrieve(customerGroupId)
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/customer-groups/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/customer-groups/index.ts

@@ -63,6 +63,7 @@ export default (app) => {
  *   - customer_group
  * properties:
  *   customer_group:
+ *     description: Customer group details.
  *     $ref: "#/components/schemas/CustomerGroup"
  */
 export type AdminCustomerGroupsRes = {
@@ -102,6 +103,7 @@ export type AdminCustomerGroupsDeleteRes = DeleteResponse
  * properties:
  *   customer_groups:
  *     type: array
+ *     description: An array of customer group details.
  *     items:
  *       $ref: "#/components/schemas/CustomerGroup"
  *   count:
@@ -109,7 +111,7 @@ export type AdminCustomerGroupsDeleteRes = DeleteResponse
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of customer groups skipped when retrieving the customer groups.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/customer-groups/list-customer-groups.ts

@@ -9,13 +9,13 @@ import { Type } from "class-transformer"
  * @oas [get] /admin/customer-groups
  * operationId: "GetCustomerGroups"
  * summary: "List Customer Groups"
- * description: "Retrieve a list of customer groups."
+ * description: "Retrieve a list of customer groups. The customer groups can be filtered by fields such as `name` or `id. The customer groups can also be sorted or paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) q {string} Query used for searching customer group names.
- *   - (query) offset=0 {integer} How many groups to skip in the result.
- *   - (query) order {string} the field used to order the customer groups.
- *   - (query) discount_condition_id {string} The discount condition id on which to filter the customer groups.
+ *   - (query) q {string} term to search customer groups by name.
+ *   - (query) offset=0 {integer} The number of customer groups to skip when retrieving the customer groups.
+ *   - (query) order {string} A field to sort order the retrieved customer groups by.
+ *   - (query) discount_condition_id {string} Filter by discount condition ID.
  *   - in: query
  *     name: id
  *     style: form
@@ -26,7 +26,7 @@ import { Type } from "class-transformer"
  *         - type: string
  *           description: customer group ID
  *         - type: array
- *           description: multiple customer group IDs
+ *           description: an array of customer group IDs
  *           items:
  *             type: string
  *         - type: object
@@ -50,13 +50,13 @@ import { Type } from "class-transformer"
  *     description: Filter by the customer group name
  *     schema:
  *       type: array
- *       description: multiple customer group names
+ *       description: an array of customer group names
  *       items:
  *         type: string
  *         description: customer group name
  *   - in: query
  *     name: created_at
- *     description: Date comparison for when resulting customer groups were created.
+ *     description: Filter by a creation date range.
  *     schema:
  *       type: object
  *       properties:
@@ -78,7 +78,7 @@ import { Type } from "class-transformer"
  *            format: date
  *   - in: query
  *     name: updated_at
- *     description: Date comparison for when resulting customer groups were updated.
+ *     description: Filter by an update date range.
  *     schema:
  *       type: object
  *       properties:
@@ -98,8 +98,8 @@ import { Type } from "class-transformer"
  *            type: string
  *            description: filter by dates greater than or equal to this date
  *            format: date
- *   - (query) limit=10 {integer} Limit the number of customer groups returned.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each customer groups of the result.
+ *   - (query) limit=10 {integer} The number of customer groups to return.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned customer groups.
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetCustomerGroupsParams
@@ -117,8 +117,8 @@ import { Type } from "class-transformer"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/customer-groups' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/customer-groups' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts

@@ -11,7 +11,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/customer-groups/{id}
  * operationId: "PostCustomerGroupsGroup"
  * summary: "Update a Customer Group"
- * description: "Update a CustomerGroup."
+ * description: "Update a Customer Group's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the customer group.
@@ -29,8 +29,8 @@ import { validator } from "../../../../utils/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.customerGroups.update(customer_group_id, {
- *         name: 'VIP'
+ *       medusa.admin.customerGroups.update(customerGroupId, {
+ *         name: "VIP"
  *       })
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
@@ -38,9 +38,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/customer-groups/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "name": "VIP"
  *       }'
@@ -114,7 +114,7 @@ export default async (req: Request, res: Response) => {
  *     description: "Name of the customer group"
  *     type: string
  *   metadata:
- *     description: "Metadata for the customer."
+ *     description: "Metadata of the customer group."
  *     type: object
  */
 export class AdminPostCustomerGroupsGroupReq {

packages/medusa/src/api/routes/admin/customers/create-customer.ts

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/customers
  * operationId: "PostCustomers"
  * summary: "Create a Customer"
- * description: "Creates a Customer."
+ * description: "Allow admins to create a customer."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -25,10 +25,10 @@ import { EntityManager } from "typeorm"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.customers.create({
- *         email: 'user@example.com',
- *         first_name: 'Caterina',
- *         last_name: 'Yost',
- *         password: 'supersecret'
+ *         email: "user@example.com",
+ *         first_name: "Caterina",
+ *         last_name: "Yost",
+ *         password: "supersecret"
  *       })
  *       .then(({ customer }) => {
  *         console.log(customer.id);
@@ -36,9 +36,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/customers' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/customers' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "email": "user@example.com",
  *           "first_name": "Caterina",

packages/medusa/src/api/routes/admin/customers/get-customer.ts

@@ -7,12 +7,12 @@ import { validator } from "../../../../utils/validator"
  * @oas [get] /admin/customers/{id}
  * operationId: "GetCustomersCustomer"
  * summary: "Get a Customer"
- * description: "Retrieves a Customer."
+ * description: "Retrieve the details of a customer."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Customer.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in the customer.
- *   - (query) fields {string} (Comma separated) Which fields should be included in the customer.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned customer.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned customer.
  * x-codegen:
  *   method: retrieve
  * x-codeSamples:
@@ -22,15 +22,15 @@ import { validator } from "../../../../utils/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.customers.retrieve(customer_id)
+ *       medusa.admin.customers.retrieve(customerId)
  *       .then(({ customer }) => {
  *         console.log(customer.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/customers/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/customers/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/customers/index.ts

@@ -32,6 +32,7 @@ export default (app) => {
  *   - customer
  * properties:
  *   customer:
+ *     description: "Customer details."
  *     $ref: "#/components/schemas/Customer"
  */
 export type AdminCustomersRes = {
@@ -49,6 +50,7 @@ export type AdminCustomersRes = {
  * properties:
  *   customers:
  *     type: array
+ *     description: "An array of customer details."
  *     items:
  *       $ref: "#/components/schemas/Customer"
  *   count:
@@ -56,7 +58,7 @@ export type AdminCustomersRes = {
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of customers skipped when retrieving the customers.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/customers/list-customers.ts

@@ -8,14 +8,22 @@ import customerController from "../../../../controllers/customers"
  * @oas [get] /admin/customers
  * operationId: "GetCustomers"
  * summary: "List Customers"
- * description: "Retrieves a list of Customers."
+ * description: "Retrieve a list of Customers. The customers can be filtered by fields such as `q` or `groups`. The customers can also be paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) limit=50 {integer} The number of items to return.
- *   - (query) offset=0 {integer} The items to skip before result.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each customer.
- *   - (query) q {string} a search term to search email, first_name, and last_name.
- *   - (query) groups[] {string} group IDs to search customers by.
+ *   - (query) limit=50 {integer} The number of customers to return.
+ *   - (query) offset=0 {integer} The number of customers to skip when retrieving the customers.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned customer.
+ *   - (query) q {string} term to search customers' email, first_name, and last_name fields.
+ *   - in: query
+ *     name: groups
+ *     style: form
+ *     explode: false
+ *     description: Filter by customer group IDs.
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetCustomersParams
@@ -33,8 +41,8 @@ import customerController from "../../../../controllers/customers"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/customers' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/customers' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/customers/update-customer.ts

@@ -19,12 +19,12 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/customers/{id}
  * operationId: "PostCustomersCustomer"
  * summary: "Update a Customer"
- * description: "Updates a Customer."
+ * description: "Update a Customer's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Customer.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each customer.
- *   - (query) fields {string} (Comma separated) Which fields should be retrieved in each customer.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned customer.
+ *   - (query) fields {string} Comma-separated fields that should be retrieved in the returned customer.
  * requestBody:
  *   content:
  *     application/json:
@@ -39,8 +39,8 @@ import { validator } from "../../../../utils/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.customers.update(customer_id, {
- *         first_name: 'Dolly'
+ *       medusa.admin.customers.update(customerId, {
+ *         first_name: "Dolly"
  *       })
  *       .then(({ customer }) => {
  *         console.log(customer.id);
@@ -48,9 +48,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/customers/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/customers/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "first_name": "Dolly"
  *       }'
@@ -147,6 +147,7 @@ class Group {
  *     format: password
  *   groups:
  *     type: array
+ *     description: A list of customer groups to which the customer belongs.
  *     items:
  *       type: object
  *       required:
@@ -155,7 +156,6 @@ class Group {
  *         id:
  *           description: The ID of a customer group
  *           type: string
- *     description: A list of customer groups to which the customer belongs.
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.
  *     type: object

packages/medusa/src/api/routes/admin/discounts/add-region.ts

@@ -7,8 +7,8 @@ import { EntityManager } from "typeorm"
 /**
  * @oas [post] /admin/discounts/{id}/regions/{region_id}
  * operationId: "PostDiscountsDiscountRegionsRegion"
- * summary: "Add Region"
- * description: "Adds a Region to the list of Regions that a Discount can be used in."
+ * summary: "Add Region to Discount"
+ * description: "Add a Region to the list of Regions a Discount can be used in."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount.
@@ -22,15 +22,15 @@ import { EntityManager } from "typeorm"
  *       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.discounts.addRegion(discount_id, region_id)
+ *       medusa.admin.discounts.addRegion(discountId, regionId)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts

@@ -13,13 +13,14 @@ import { FindParams } from "../../../../types/common"
  * @oas [post] /admin/discounts/{discount_id}/conditions/{condition_id}/batch
  * operationId: "PostDiscountsDiscountConditionsConditionBatch"
  * summary: "Add Batch Resources"
- * description: "Add a batch of resources to a discount condition."
+ * description: "Add a batch of resources to a discount condition. The type of resource depends on the type of discount condition. For example, if the discount condition's type is `products`,
+ * the resources being added should be products."
  * x-authenticated: true
  * parameters:
- *   - (path) discount_id=* {string} The ID of the Product.
- *   - (path) condition_id=* {string} The ID of the condition on which to add the item.
- *   - (query) expand {string} (Comma separated) Which relations should be expanded in each discount of the result.
- *   - (query) fields {string} (Comma separated) Which fields should be included in each discount of the result.
+ *   - (path) discount_id=* {string} The ID of the discount the condition belongs to.
+ *   - (path) condition_id=* {string} The ID of the discount condition on which to add the item.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * requestBody:
  *   content:
  *     application/json:
@@ -35,8 +36,8 @@ 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.discounts.addConditionResourceBatch(discount_id, condition_id, {
- *         resources: [{ id: item_id }]
+ *       medusa.admin.discounts.addConditionResourceBatch(discountId, conditionId, {
+ *         resources: [{ id: itemId }]
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
@@ -44,9 +45,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "resources": [{ "id": "item_id" }]
  *       }'

packages/medusa/src/api/routes/admin/discounts/create-condition.ts

@@ -12,12 +12,13 @@ import { FindParams } from "../../../../types/common"
  * @oas [post] /admin/discounts/{discount_id}/conditions
  * operationId: "PostDiscountsDiscountConditions"
  * summary: "Create a Condition"
- * description: "Creates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
+ * description: "Create a Discount Condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided, based on the type of discount condition.
+ *  For example, if the discount condition's type is `products`, the `products` field should be provided in the request body."
  * x-authenticated: true
  * parameters:
- *   - (path) discount_id=* {string} The ID of the Product.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each product of the result.
- *   - (query) fields {string} (Comma separated) Which fields should be included in each product of the result.
+ *   - (path) discount_id=* {string} The ID of the discount.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * requestBody:
  *   content:
  *     application/json:
@@ -34,7 +35,7 @@ import { FindParams } from "../../../../types/common"
  *       import { DiscountConditionOperator } from "@medusajs/medusa"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
- *       medusa.admin.discounts.createCondition(discount_id, {
+ *       medusa.admin.discounts.createCondition(discountId, {
  *         operator: DiscountConditionOperator.IN
  *       })
  *       .then(({ discount }) => {
@@ -43,9 +44,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "operator": "in"
  *       }'
@@ -105,32 +106,33 @@ export default async (req: Request, res: Response) => {
  *   - operator
  * properties:
  *   operator:
- *      description: Operator of the condition
+ *      description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
+ *       discountable resources are everything but the specified resources."
  *      type: string
  *      enum: [in, not_in]
  *   products:
  *      type: array
- *      description: list of product IDs if the condition is applied on products.
+ *      description: list of product IDs if the condition's type is `products`.
  *      items:
  *        type: string
  *   product_types:
  *      type: array
- *      description: list of product type IDs if the condition is applied on product types.
+ *      description: list of product type IDs if the condition's type is `product_types`.
  *      items:
  *        type: string
  *   product_collections:
  *      type: array
- *      description: list of product collection IDs if the condition is applied on product collections.
+ *      description: list of product collection IDs if the condition's type is `product_collections`.
  *      items:
  *        type: string
  *   product_tags:
  *      type: array
- *      description: list of product tag IDs if the condition is applied on product tags.
+ *      description: list of product tag IDs if the condition's type is `product_tags`.
  *      items:
  *        type: string
  *   customer_groups:
  *      type: array
- *      description: list of customer group IDs if the condition is applied on customer groups.
+ *      description: list of customer group IDs if the condition's type is `customer_groups`.
  *      items:
  *        type: string
  */

packages/medusa/src/api/routes/admin/discounts/create-discount.ts

@@ -28,12 +28,12 @@ import { FindParams } from "../../../../types/common"
 /**
  * @oas [post] /admin/discounts
  * operationId: "PostDiscounts"
- * summary: "Creates a Discount"
+ * summary: "Create a Discount"
  * x-authenticated: true
- * description: "Creates a Discount with a given set of rules that define how the Discount behaves."
+ * description: "Create a Discount with a given set of rules that defines how the Discount is applied."
  * parameters:
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in the results.
- *   - (query) fields {string} (Comma separated) Which fields should be retrieved in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be retrieved in the returned discount.
  * requestBody:
  *   content:
  *     application/json:
@@ -51,7 +51,7 @@ import { FindParams } from "../../../../types/common"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.discounts.create({
- *         code: 'TEST',
+ *         code: "TEST",
  *         rule: {
  *           type: DiscountRuleType.FIXED,
  *           value: 10,
@@ -67,9 +67,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/discounts' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "code": "TEST",
  *           "rule": {
@@ -133,13 +133,13 @@ export default async (req: Request, res: Response) => {
  * properties:
  *   code:
  *     type: string
- *     description: A unique code that will be used to redeem the Discount
+ *     description: A unique code that will be used to redeem the discount
  *   is_dynamic:
  *     type: boolean
- *     description: Whether the Discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated codes that all have to follow a common set of rules.
+ *     description: Whether the discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated discount codes that all have to follow a common set of rules.
  *     default: false
  *   rule:
- *     description: The Discount Rule that defines how Discounts are calculated
+ *     description: The discount rule that defines how discounts are calculated
  *     type: object
  *     required:
  *        - type
@@ -151,18 +151,18 @@ export default async (req: Request, res: Response) => {
  *         description: "A short description of the discount"
  *       type:
  *         type: string
- *         description: "The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers."
+ *         description: "The type of the discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers."
  *         enum: [fixed, percentage, free_shipping]
  *       value:
  *         type: number
- *         description: "The value that the discount represents; this will depend on the type of the discount"
+ *         description: "The value that the discount represents. This will depend on the type of the discount."
  *       allocation:
  *         type: string
- *         description: "The scope that the discount should apply to."
+ *         description: "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart."
  *         enum: [total, item]
  *       conditions:
  *         type: array
- *         description: "A set of conditions that can be used to limit when  the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
+ *         description: "A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided based on the discount condition's type."
  *         items:
  *           type: object
  *           required:
@@ -170,57 +170,58 @@ export default async (req: Request, res: Response) => {
  *           properties:
  *             operator:
  *               type: string
- *               description: Operator of the condition
+ *               description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
+ *                discountable resources are everything but the specified resources."
  *               enum: [in, not_in]
  *             products:
  *               type: array
- *               description: list of product IDs if the condition is applied on products.
+ *               description: list of product IDs if the condition's type is `products`.
  *               items:
  *                 type: string
  *             product_types:
  *               type: array
- *               description: list of product type IDs if the condition is applied on product types.
+ *               description: list of product type IDs if the condition's type is `product_types`.
  *               items:
  *                 type: string
  *             product_collections:
  *               type: array
- *               description: list of product collection IDs if the condition is applied on product collections.
+ *               description: list of product collection IDs if the condition's type is `product_collections`.
  *               items:
  *                 type: string
  *             product_tags:
  *               type: array
- *               description: list of product tag IDs if the condition is applied on product tags.
+ *               description: list of product tag IDs if the condition's type is `product_tags`.
  *               items:
  *                 type: string
  *             customer_groups:
  *               type: array
- *               description: list of customer group IDs if the condition is applied on customer groups.
+ *               description: list of customer group IDs if the condition's type is `customer_groups`.
  *               items:
  *                 type: string
  *   is_disabled:
  *     type: boolean
- *     description: Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers.
+ *     description: Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.
  *     default: false
  *   starts_at:
  *     type: string
  *     format: date-time
- *     description: The time at which the Discount should be available.
+ *     description: The date and time at which the discount should be available.
  *   ends_at:
  *     type: string
  *     format: date-time
- *     description: The time at which the Discount should no longer be available.
+ *     description: The date and time at which the discount should no longer be available.
  *   valid_duration:
  *     type: string
- *     description: Duration the discount runs between
+ *     description: The duration the discount runs between
  *     example: P3Y6M4DT12H30M5S
  *   regions:
- *     description: A list of Region ids representing the Regions in which the Discount can be used.
+ *     description: A list of region IDs representing the Regions in which the Discount can be used.
  *     type: array
  *     items:
  *       type: string
  *   usage_limit:
  *     type: number
- *     description: Maximum times the discount can be used
+ *     description: Maximum number of times the discount can be used
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.
  *     type: object

packages/medusa/src/api/routes/admin/discounts/create-dynamic-code.ts

@@ -15,10 +15,10 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/discounts/{id}/dynamic-codes
  * operationId: "PostDiscountsDiscountDynamicCodes"
  * summary: "Create a Dynamic Code"
- * description: "Creates a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same behaviour."
+ * description: "Create a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same rules and conditions."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The ID of the Discount to create the dynamic code from."
+ *   - (path) id=* {string} The ID of the Discount to create the dynamic code for."
  * requestBody:
  *  content:
  *    application/json:
@@ -33,8 +33,8 @@ import { EntityManager } from "typeorm"
  *       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.discounts.createDynamicCode(discount_id, {
- *         code: 'TEST',
+ *       medusa.admin.discounts.createDynamicCode(discountId, {
+ *         code: "TEST",
  *         usage_limit: 1
  *       })
  *       .then(({ discount }) => {
@@ -43,9 +43,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "code": "TEST"
  *       }'
@@ -107,7 +107,7 @@ export default async (req: Request, res: Response) => {
  *     description: A unique code that will be used to redeem the Discount
  *   usage_limit:
  *     type: number
- *     description: Maximum times the discount can be used
+ *     description: Maximum number of times the discount code can be used
  *     default: 1
  *   metadata:
  *     type: object

packages/medusa/src/api/routes/admin/discounts/delete-condition.ts

@@ -8,13 +8,13 @@ import { FindParams } from "../../../../types/common"
  * @oas [delete] /admin/discounts/{discount_id}/conditions/{condition_id}
  * operationId: "DeleteDiscountsDiscountConditionsCondition"
  * summary: "Delete a Condition"
- * description: "Deletes a DiscountCondition"
+ * description: "Deletes a Discount Condition. This does not delete resources associated to the discount condition."
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the Discount
- *   - (path) condition_id=* {string} The ID of the DiscountCondition
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (path) condition_id=* {string} The ID of the Discount Condition
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * x-codegen:
  *   method: deleteCondition
  *   queryParams: AdminDeleteDiscountsDiscountConditionsConditionParams
@@ -25,15 +25,15 @@ 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.discounts.deleteCondition(discount_id, condition_id)
+ *       medusa.admin.discounts.deleteCondition(discountId, conditionId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/delete-discount.ts

@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
  * @oas [delete] /admin/discounts/{id}
  * operationId: "DeleteDiscountsDiscount"
  * summary: "Delete a Discount"
- * description: "Deletes a Discount."
+ * description: "Delete a Discount. Deleting the discount will make it unavailable for customers to use."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount
@@ -18,15 +18,15 @@ import { EntityManager } from "typeorm"
  *       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.discounts.delete(discount_id)
+ *       medusa.admin.discounts.delete(discountId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts

@@ -7,11 +7,11 @@ import { EntityManager } from "typeorm"
  * @oas [delete] /admin/discounts/{id}/dynamic-codes/{code}
  * operationId: "DeleteDiscountsDiscountDynamicCodesCode"
  * summary: "Delete a Dynamic Code"
- * description: "Deletes a dynamic code from a Discount."
+ * description: "Delete a dynamic code from a Discount."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount
- *   - (path) code=* {string} The ID of the Discount
+ *   - (path) code=* {string} The dynamic code to delete
  * x-codegen:
  *   method: deleteDynamicCode
  * x-codeSamples:
@@ -21,15 +21,15 @@ import { EntityManager } from "typeorm"
  *       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.discounts.deleteDynamicCode(discount_id, code)
+ *       medusa.admin.discounts.deleteDynamicCode(discountId, code)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts

@@ -11,14 +11,14 @@ import { FindParams } from "../../../../types/common"
 /**
  * @oas [delete] /admin/discounts/{discount_id}/conditions/{condition_id}/batch
  * operationId: "DeleteDiscountsDiscountConditionsConditionBatch"
- * summary: "Delete Batch Resources"
- * description: "Delete a batch of resources from a discount condition."
+ * summary: "Remove Batch Resources"
+ * description: "Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, but not the resource itself."
  * x-authenticated: true
  * parameters:
- *   - (path) discount_id=* {string} The ID of the Product.
- *   - (path) condition_id=* {string} The ID of the condition on which to add the item.
- *   - (query) expand {string} (Comma separated) Which relations should be expanded in each discount of the result.
- *   - (query) fields {string} (Comma separated) Which fields should be included in each discount of the result.
+ *   - (path) discount_id=* {string} The ID of the discount.
+ *   - (path) condition_id=* {string} The ID of the condition to remove the resources from.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * requestBody:
  *   content:
  *     application/json:
@@ -33,8 +33,8 @@ 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.discounts.deleteConditionResourceBatch(discount_id, condition_id, {
- *         resources: [{ id: item_id }]
+ *       medusa.admin.discounts.deleteConditionResourceBatch(discountId, conditionId, {
+ *         resources: [{ id: itemId }]
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
@@ -42,9 +42,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "resources": [{ "id": "item_id" }]
  *       }'
@@ -119,7 +119,7 @@ export class AdminDeleteDiscountsDiscountConditionsConditionBatchParams extends
  *   - resources
  * properties:
  *   resources:
- *     description: The resources to be deleted from the discount condition
+ *     description: The resources to be removed from the discount condition
  *     type: array
  *     items:
  *       type: object

packages/medusa/src/api/routes/admin/discounts/get-condition.ts

@@ -6,13 +6,13 @@ import { FindParams } from "../../../../types/common"
  * @oas [get] /admin/discounts/{discount_id}/conditions/{condition_id}
  * operationId: "GetDiscountsDiscountConditionsCondition"
  * summary: "Get a Condition"
- * description: "Gets a DiscountCondition"
+ * description: "Retrieve a Discount Condition's details."
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the Discount.
- *   - (path) condition_id=* {string} The ID of the DiscountCondition.
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (path) condition_id=* {string} The ID of the Discount Condition.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount condition.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount condition.
  * x-codegen:
  *   method: getCondition
  *   queryParams: AdminGetDiscountsDiscountConditionsConditionParams
@@ -23,15 +23,15 @@ 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.discounts.getCondition(discount_id, condition_id)
+ *       medusa.admin.discounts.getCondition(discountId, conditionId)
  *       .then(({ discount_condition }) => {
  *         console.log(discount_condition.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts

@@ -6,12 +6,12 @@ import { FindParams } from "../../../../types/common"
  * @oas [get] /admin/discounts/code/{code}
  * operationId: "GetDiscountsDiscountCode"
  * summary: "Get Discount by Code"
- * description: "Retrieves a Discount by its discount code"
+ * description: "Retrieve a Discount's details by its discount code"
  * x-authenticated: true
  * parameters:
  *   - (path) code=* {string} The code of the Discount
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * x-codegen:
  *   method: retrieveByCode
  *   queryParams: AdminGetDiscountsDiscountCodeParams
@@ -29,8 +29,8 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/discounts/code/{code}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/discounts/code/{code}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/get-discount.ts

@@ -10,8 +10,8 @@ import { FindParams } from "../../../../types/common"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * x-codegen:
  *   method: retrieve
  *   queryParams: AdminGetDiscountParams
@@ -22,15 +22,15 @@ 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.discounts.retrieve(discount_id)
+ *       medusa.admin.discounts.retrieve(discountId)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/discounts/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/index.ts

@@ -236,6 +236,7 @@ export const defaultAdminDiscountConditionRelations = ["discount_rule"]
  *   - discount
  * properties:
  *   discount:
+ *     description: "Discount details."
  *     $ref: "#/components/schemas/Discount"
  */
 export type AdminDiscountsRes = {
@@ -253,6 +254,7 @@ export type AdminDiscountsRes = {
  *   - discount_condition
  * properties:
  *   discount_condition:
+ *     description: "Discount condition details."
  *     $ref: "#/components/schemas/DiscountCondition"
  */
 export type AdminDiscountConditionsRes = {
@@ -276,7 +278,7 @@ export type AdminDiscountConditionsRes = {
  *     default: discount
  *   deleted:
  *     type: boolean
- *     description: Whether the discount was deleted successfully or not.
+ *     description: Whether the discount was deleted successfully.
  *     default: true
  */
 export type AdminDiscountsDeleteRes = DeleteResponse
@@ -292,17 +294,17 @@ export type AdminDiscountsDeleteRes = DeleteResponse
  * properties:
  *   id:
  *     type: string
- *     description: The ID of the deleted DiscountCondition
+ *     description: The ID of the deleted Discount Condition
  *   object:
  *     type: string
  *     description: The type of the object that was deleted.
  *     default: discount-condition
  *   deleted:
  *     type: boolean
- *     description: Whether the discount condition was deleted successfully or not.
+ *     description: Whether the discount condition was deleted successfully.
  *     default: true
  *   discount:
- *     description: The Discount to which the condition used to belong
+ *     description: The Discount to which the condition used to belong to.
  *     $ref: "#/components/schemas/Discount"
  */
 export type AdminDiscountConditionsDeleteRes = DeleteResponse & {
@@ -334,7 +336,7 @@ export type AdminDiscountConditionsDeleteRes = DeleteResponse & {
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of discounts skipped when retrieving the discounts.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/discounts/list-discounts.ts

@@ -17,28 +17,28 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean"
  * operationId: "GetDiscounts"
  * summary: "List Discounts"
  * x-authenticated: true
- * description: "Retrieves a list of Discounts"
+ * description: "Retrieve a list of Discounts. The discounts can be filtered by fields such as `rule` or `is_dynamic`. The discounts can also be paginated."
  * parameters:
- *   - (query) q {string} Search query applied on the code field.
+ *   - (query) q {string} term to search discounts' code field.
  *   - in: query
  *     name: rule
- *     description: Discount Rules filters to apply on the search
+ *     description: Filter discounts by rule fields.
  *     schema:
  *       type: object
  *       properties:
  *         type:
  *           type: string
  *           enum: [fixed, percentage, free_shipping]
- *           description: "The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers."
+ *           description: "Filter discounts by type."
  *         allocation:
  *           type: string
  *           enum: [total, item]
- *           description: "The value that the discount represents; this will depend on the type of the discount"
- *   - (query) is_dynamic {boolean} Return only dynamic discounts.
- *   - (query) is_disabled {boolean} Return only disabled discounts.
- *   - (query) limit=20 {number} The number of items in the response
- *   - (query) offset=0 {number} The offset of items in response
- *   - (query) expand {string} Comma separated list of relations to include in the results.
+ *           description: "Filter discounts by allocation type."
+ *   - (query) is_dynamic {boolean} Filter discounts by whether they're dynamic or not.
+ *   - (query) is_disabled {boolean} Filter discounts by whether they're disabled or not.
+ *   - (query) limit=20 {number} The number of discounts to return
+ *   - (query) offset=0 {number} The number of discounts to skip when retrieving the discounts.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in each returned discount.
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetDiscountsParams
@@ -56,8 +56,8 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/discounts' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/discounts' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/remove-region.ts

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * operationId: "DeleteDiscountsDiscountRegionsRegion"
  * summary: "Remove Region"
  * x-authenticated: true
- * description: "Removes a Region from the list of Regions that a Discount can be used in."
+ * description: "Remove a Region from the list of Regions that a Discount can be used in. This does not delete a region, only the association between it and the discount."
  * parameters:
  *   - (path) id=* {string} The ID of the Discount.
  *   - (path) region_id=* {string} The ID of the Region.
@@ -21,15 +21,15 @@ import { EntityManager } from "typeorm"
  *       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.discounts.removeRegion(discount_id, region_id)
+ *       medusa.admin.discounts.removeRegion(discountId, regionId)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/discounts/update-condition.ts

@@ -9,13 +9,14 @@ import { FindParams } from "../../../../types/common"
  * @oas [post] /admin/discounts/{discount_id}/conditions/{condition_id}
  * operationId: "PostDiscountsDiscountConditionsCondition"
  * summary: "Update a Condition"
- * description: "Updates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
+ * description: "Update a Discount Condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided, based on the type of discount condition.
+ *  For example, if the discount condition's type is `products`, the `products` field should be provided in the request body."
  * x-authenticated: true
  * parameters:
- *   - (path) discount_id=* {string} The ID of the Product.
- *   - (path) condition_id=* {string} The ID of the DiscountCondition.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each item of the result.
- *   - (query) fields {string} (Comma separated) Which fields should be included in each item of the result.
+ *   - (path) discount_id=* {string} The ID of the Discount.
+ *   - (path) condition_id=* {string} The ID of the Discount Condition.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned discount.
  * requestBody:
  *   content:
  *     application/json:
@@ -31,9 +32,9 @@ 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.discounts.updateCondition(discount_id, condition_id, {
+ *       medusa.admin.discounts.updateCondition(discountId, conditionId, {
  *         products: [
- *           product_id
+ *           productId
  *         ]
  *       })
  *       .then(({ discount }) => {
@@ -42,9 +43,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "products": [
  *              "prod_01G1G5V2MBA328390B5AXJ610F"
@@ -113,27 +114,27 @@ export default async (req: Request, res: Response) => {
  * properties:
  *   products:
  *      type: array
- *      description: list of product IDs if the condition is applied on products.
+ *      description: list of product IDs if the condition's type is `products`.
  *      items:
  *        type: string
  *   product_types:
  *      type: array
- *      description: list of product type IDs if the condition is applied on product types.
+ *      description: list of product type IDs if the condition's type is `product_types`.
  *      items:
  *        type: string
  *   product_collections:
  *      type: array
- *      description: list of product collection IDs if the condition is applied on product collections.
+ *      description: list of product collection IDs if the condition's type is `product_collections`.
  *      items:
  *        type: string
  *   product_tags:
  *      type: array
- *      description: list of product tag IDs if the condition is applied on product tags.
+ *      description: list of product tag IDs if the condition's type is `product_tags`
  *      items:
  *        type: string
  *   customer_groups:
  *      type: array
- *      description: list of customer group IDs if the condition is applied on customer groups.
+ *      description: list of customer group IDs if the condition's type is `customer_groups`.
  *      items:
  *        type: string
  */

packages/medusa/src/api/routes/admin/discounts/update-discount.ts

@@ -26,12 +26,12 @@ import { FindParams } from "../../../../types/common"
  * @oas [post] /admin/discounts/{id}
  * operationId: "PostDiscountsDiscount"
  * summary: "Update a Discount"
- * description: "Updates a Discount with a given set of rules that define how the Discount behaves."
+ * description: "Update a Discount with a given set of rules that define how the Discount is applied."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount.
- *   - (query) expand {string} (Comma separated) Which fields should be expanded in each item of the result.
- *   - (query) fields {string} (Comma separated) Which fields should be included in each item of the result.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned discount.
+ *   - (query) fields {string} Comma-separated fields that should be retrieved in the returned discount.
  * requestBody:
  *   content:
  *     application/json:
@@ -47,8 +47,8 @@ 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.discounts.update(discount_id, {
- *         code: 'TEST'
+ *       medusa.admin.discounts.update(discountId, {
+ *         code: "TEST"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
@@ -56,9 +56,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/discounts/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "code": "TEST"
  *       }'
@@ -113,9 +113,9 @@ export default async (req: Request, res: Response) => {
  * properties:
  *   code:
  *     type: string
- *     description: A unique code that will be used to redeem the Discount
+ *     description: A unique code that will be used to redeem the discount
  *   rule:
- *     description: The Discount Rule that defines how Discounts are calculated
+ *     description: The discount rule that defines how discounts are calculated
  *     type: object
  *     required:
  *       - id
@@ -128,14 +128,14 @@ export default async (req: Request, res: Response) => {
  *         description: "A short description of the discount"
  *       value:
  *         type: number
- *         description: "The value that the discount represents; this will depend on the type of the discount"
+ *         description: "The value that the discount represents. This will depend on the type of the discount."
  *       allocation:
  *         type: string
- *         description: "The scope that the discount should apply to."
+ *         description: "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart."
  *         enum: [total, item]
  *       conditions:
  *         type: array
- *         description: "A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
+ *         description: "A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided based on the discount condition's type."
  *         items:
  *           type: object
  *           required:
@@ -143,56 +143,57 @@ export default async (req: Request, res: Response) => {
  *           properties:
  *             id:
  *               type: string
- *               description: "The ID of the Rule"
+ *               description: "The ID of the condition"
  *             operator:
  *               type: string
- *               description: Operator of the condition
+ *               description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
+ *                discountable resources are everything but the specified resources."
  *               enum: [in, not_in]
  *             products:
  *               type: array
- *               description: list of product IDs if the condition is applied on products.
+ *               description: list of product IDs if the condition's type is `products`.
  *               items:
  *                 type: string
  *             product_types:
  *               type: array
- *               description: list of product type IDs if the condition is applied on product types.
+ *               description: list of product type IDs if the condition's type is `product_types`.
  *               items:
  *                 type: string
  *             product_collections:
  *               type: array
- *               description: list of product collection IDs if the condition is applied on product collections.
+ *               description: list of product collection IDs if the condition's type is `product_collections`.
  *               items:
  *                 type: string
  *             product_tags:
  *               type: array
- *               description: list of product tag IDs if the condition is applied on product tags.
+ *               description: list of product tag IDs if the condition's type is `product_tags`.
  *               items:
  *                 type: string
  *             customer_groups:
  *               type: array
- *               description: list of customer group IDs if the condition is applied on customer groups.
+ *               description: list of customer group IDs if the condition's type is `customer_groups`.
  *               items:
  *                 type: string
  *   is_disabled:
  *     type: boolean
- *     description: Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers.
+ *     description: Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.
  *   starts_at:
  *     type: string
  *     format: date-time
- *     description: The time at which the Discount should be available.
+ *     description: The date and time at which the discount should be available.
  *   ends_at:
  *     type: string
  *     format: date-time
- *     description: The time at which the Discount should no longer be available.
+ *     description: The date and time at which the discount should no longer be available.
  *   valid_duration:
  *     type: string
- *     description: Duration the discount runs between
+ *     description: The duration the discount runs between
  *     example: P3Y6M4DT12H30M5S
  *   usage_limit:
  *     type: number
- *     description: Maximum times the discount can be used
+ *     description: Maximum number of times the discount can be used
  *   regions:
- *     description: A list of Region ids representing the Regions in which the Discount can be used.
+ *     description: A list of region IDs representing the Regions in which the Discount can be used.
  *     type: array
  *     items:
  *       type: string

packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts

@@ -31,7 +31,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [post] /admin/draft-orders
  * operationId: "PostDraftOrders"
  * summary: "Create a Draft Order"
- * description: "Creates a Draft Order"
+ * description: "Create a Draft Order. A draft order is not transformed into an order until payment is captured."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -48,7 +48,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.draftOrders.create({
- *         email: 'user@example.com',
+ *         email: "user@example.com",
  *         region_id,
  *         items: [
  *           {
@@ -67,9 +67,9 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/draft-orders' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "email": "user@example.com",
  *           "region_id": "{region_id}"
@@ -172,7 +172,7 @@ enum Status {
  *   - shipping_methods
  * properties:
  *   status:
- *     description: "The status of the draft order"
+ *     description: "The status of the draft order. The draft order's default status is `open`. It's changed to `completed` when its payment is marked as paid."
  *     type: string
  *     enum: [open, completed]
  *   email:
@@ -185,12 +185,12 @@ enum Status {
  *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   shipping_address:
- *     description: "The Address to be used for shipping."
+ *     description: "The Address to be used for shipping purposes."
  *     anyOf:
  *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   items:
- *     description: The Line Items that have been received.
+ *     description: The draft order's line items.
  *     type: array
  *     items:
  *       type: object
@@ -198,25 +198,25 @@ enum Status {
  *         - quantity
  *       properties:
  *         variant_id:
- *           description: The ID of the Product Variant to generate the Line Item from.
+ *           description: The ID of the Product Variant associated with the line item. If the line item is custom, the `variant_id` should be omitted.
  *           type: string
  *         unit_price:
- *           description: The potential custom price of the item.
+ *           description: The custom price of the line item. If a `variant_id` is supplied, the price provided here will override the variant's price.
  *           type: integer
  *         title:
- *           description: The potential custom title of the item.
+ *           description: The title of the line item if `variant_id` is not provided.
  *           type: string
  *         quantity:
- *           description: The quantity of the Line Item.
+ *           description: The quantity of the line item.
  *           type: integer
  *         metadata:
- *           description: The optional key-value map with additional details about the Line Item.
+ *           description: The optional key-value map with additional details about the line item.
  *           type: object
  *   region_id:
  *     description: The ID of the region for the draft order
  *     type: string
  *   discounts:
- *     description: The discounts to add on the draft order
+ *     description: The discounts to add to the draft order
  *     type: array
  *     items:
  *       type: object
@@ -227,10 +227,10 @@ enum Status {
  *           description: The code of the discount to apply
  *           type: string
  *   customer_id:
- *     description: The ID of the customer to add on the draft order
+ *     description: The ID of the customer this draft order is associated with.
  *     type: string
  *   no_notification_order:
- *     description: An optional flag passed to the resulting order to determine use of notifications.
+ *     description: An optional flag passed to the resulting order that indicates whether the customer should receive notifications about order updates.
  *     type: boolean
  *   shipping_methods:
  *     description: The shipping methods for the draft order
@@ -247,7 +247,7 @@ enum Status {
  *           description: The optional additional data needed for the shipping method
  *           type: object
  *         price:
- *           description: The potential custom price of the shipping
+ *           description: The price of the shipping method.
  *           type: integer
  *   metadata:
  *     description: The optional key-value map with additional details about the Draft Order.

packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts

@@ -19,7 +19,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [post] /admin/draft-orders/{id}/line-items
  * operationId: "PostDraftOrdersDraftOrderLineItems"
  * summary: "Create a Line Item"
- * description: "Creates a Line Item for the Draft Order"
+ * description: "Create a Line Item in the Draft Order."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -37,7 +37,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       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.draftOrders.addLineItem(draft_order_id, {
+ *       medusa.admin.draftOrders.addLineItem(draftOrderId, {
  *         quantity: 1
  *       })
  *       .then(({ draft_order }) => {
@@ -46,9 +46,9 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "quantity": 1
  *       }'
@@ -152,17 +152,17 @@ export default async (req, res) => {
  *   - quantity
  * properties:
  *   variant_id:
- *     description: The ID of the Product Variant to generate the Line Item from.
+ *     description: The ID of the Product Variant associated with the line item. If the line item is custom, the `variant_id` should be omitted.
  *     type: string
  *   unit_price:
- *     description: The potential custom price of the item.
+ *     description: The custom price of the line item. If a `variant_id` is supplied, the price provided here will override the variant's price.
  *     type: integer
  *   title:
- *     description: The potential custom title of the item.
+ *     description: The title of the line item if `variant_id` is not provided.
  *     type: string
  *     default: "Custom item"
  *   quantity:
- *     description: The quantity of the Line Item.
+ *     description: The quantity of the line item.
  *     type: integer
  *   metadata:
  *     description: The optional key-value map with additional details about the Line Item.

packages/medusa/src/api/routes/admin/draft-orders/delete-draft-order.ts

@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
  * @oas [delete] /admin/draft-orders/{id}
  * operationId: DeleteDraftOrdersDraftOrder
  * summary: Delete a Draft Order
- * description: "Deletes a Draft Order"
+ * description: "Delete a Draft Order"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -18,15 +18,15 @@ import { EntityManager } from "typeorm"
  *       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.draftOrders.delete(draft_order_id)
+ *       medusa.admin.draftOrders.delete(draftOrderId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/draft-orders/delete-line-item.ts

@@ -14,11 +14,11 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [delete] /admin/draft-orders/{id}/line-items/{line_id}
  * operationId: DeleteDraftOrdersDraftOrderLineItemsItem
  * summary: Delete a Line Item
- * description: "Removes a Line Item from a Draft Order."
+ * description: "Deletes a Line Item from a Draft Order."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
- *   - (path) line_id=* {string} The ID of the Draft Order.
+ *   - (path) line_id=* {string} The ID of the line item.
  * x-codegen:
  *   method: removeLineItem
  * x-codeSamples:
@@ -28,15 +28,15 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       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.draftOrders.removeLineItem(draft_order_id, item_id)
+ *       medusa.admin.draftOrders.removeLineItem(draftOrderId, itemId)
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/draft-orders/get-draft-order.ts

@@ -13,7 +13,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [get] /admin/draft-orders/{id}
  * operationId: "GetDraftOrdersDraftOrder"
  * summary: "Get a Draft Order"
- * description: "Retrieves a Draft Order."
+ * description: "Retrieve a Draft Order's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -26,15 +26,15 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       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.draftOrders.retrieve(draft_order_id)
+ *       medusa.admin.draftOrders.retrieve(draftOrderId)
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/draft-orders/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/draft-orders/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/draft-orders/index.ts

@@ -98,6 +98,7 @@ export const defaultAdminDraftOrdersFields: (keyof DraftOrder)[] = [
  *   - order
  * properties:
  *   order:
+ *     description: Order's details.
  *     $ref: "#/components/schemas/Order"
  */
 export type AdminPostDraftOrdersDraftOrderRegisterPaymentRes = {
@@ -169,6 +170,7 @@ export type AdminPostDraftOrdersDraftOrderRegisterPaymentRes = {
  *   - draft_order
  * properties:
  *   draft_order:
+ *     description: Draft order's details.
  *     $ref: "#/components/schemas/DraftOrder"
  */
 export type AdminDraftOrdersRes = {
@@ -192,7 +194,7 @@ export type AdminDraftOrdersRes = {
  *     default: draft-order
  *   deleted:
  *     type: boolean
- *     description: Whether the draft order was deleted successfully or not.
+ *     description: Whether the draft order was deleted successfully.
  *     default: true
  */
 export type AdminDraftOrdersDeleteRes = DeleteResponse
@@ -215,6 +217,7 @@ export type AdminDraftOrdersDeleteRes = DeleteResponse
  * properties:
  *   draft_orders:
  *     type: array
+ *     description: An array of draft order's details.
  *     items:
  *       $ref: "#/components/schemas/DraftOrder"
  *   count:
@@ -222,7 +225,7 @@ export type AdminDraftOrdersDeleteRes = DeleteResponse
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of draft orders skipped when retrieving the draft orders.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/draft-orders/list-draft-orders.ts

@@ -15,12 +15,12 @@ import { validator } from "../../../../utils/validator"
  * @oas [get] /admin/draft-orders
  * operationId: "GetDraftOrders"
  * summary: "List Draft Orders"
- * description: "Retrieves an list of Draft Orders"
+ * description: "Retrieve an list of Draft Orders. The draft orders can be filtered by fields such as `q`. The draft orders can also paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) offset=0 {number} The number of items to skip before the results.
- *   - (query) limit=50 {number} Limit the number of items returned.
- *   - (query) q {string} a search term to search emails in carts associated with draft orders and display IDs of draft orders
+ *   - (query) offset=0 {number} The number of draft orders to skip when retrieving the draft orders.
+ *   - (query) limit=50 {number} Limit the number of draft orders returned.
+ *   - (query) q {string} a term to search draft orders' display IDs and emails in the draft order's cart
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetDraftOrdersParams
@@ -38,8 +38,8 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/draft-orders' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/draft-orders' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/draft-orders/register-payment.ts

@@ -17,12 +17,13 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
 
 /**
  * @oas [post] /admin/draft-orders/{id}/pay
- * summary: "Registers a Payment"
+ * summary: "Mark Paid"
  * operationId: "PostDraftOrdersDraftOrderRegisterPayment"
- * description: "Registers a payment for a Draft Order."
+ * description: "Capture the draft order's payment. This will also set the draft order's status to `completed` and create an Order from the draft order. The payment is captured through Medusa's system payment,
+ *  which is manual payment that isn't integrated with any third-party payment provider. It is assumed that the payment capturing is handled manually by the admin."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {String} The Draft Order id.
+ *   - (path) id=* {String} The Draft Order ID.
  * x-codegen:
  *   method: markPaid
  * x-codeSamples:
@@ -32,15 +33,15 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       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.draftOrders.markPaid(draft_order_id)
+ *       medusa.admin.draftOrders.markPaid(draftOrderId)
  *       .then(({ order }) => {
  *         console.log(order.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts

@@ -25,7 +25,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [post] /admin/draft-orders/{id}
  * operationId: PostDraftOrdersDraftOrder
  * summary: Update a Draft Order
- * description: "Updates a Draft Order."
+ * description: "Update a Draft Order's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -43,7 +43,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       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.draftOrders.update(draft_order_id, {
+ *       medusa.admin.draftOrders.update(draftOrderId, {
  *         email: "user@example.com"
  *       })
  *       .then(({ draft_order }) => {
@@ -52,9 +52,9 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "email": "user@example.com"
  *       }'
@@ -156,7 +156,7 @@ export default async (req, res) => {
  *        description: See a list of codes.
  *   email:
  *     type: string
- *     description: "An email to be used on the Draft Order."
+ *     description: "An email to be used in the Draft Order."
  *     format: email
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
@@ -164,7 +164,7 @@ export default async (req, res) => {
  *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   shipping_address:
- *     description: "The Address to be used for shipping."
+ *     description: "The Address to be used for shipping purposes."
  *     anyOf:
  *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
@@ -180,10 +180,10 @@ export default async (req, res) => {
  *           description: "The code that a Discount is identifed by."
  *           type: string
  *   no_notification_order:
- *     description: "An optional flag passed to the resulting order to determine use of notifications."
+ *     description: "An optional flag passed to the resulting order that indicates whether the customer should receive notifications about order updates."
  *     type: boolean
  *   customer_id:
- *     description: "The ID of the Customer to associate the Draft Order with."
+ *     description: "The ID of the customer this draft order is associated with."
  *     type: string
  */
 export class AdminPostDraftOrdersDraftOrderReq {

packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts

@@ -17,7 +17,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [post] /admin/draft-orders/{id}/line-items/{line_id}
  * operationId: "PostDraftOrdersDraftOrderLineItemsItem"
  * summary: "Update a Line Item"
- * description: "Updates a Line Item for a Draft Order"
+ * description: "Update a Line Item in a Draft Order"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -36,7 +36,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       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.draftOrders.updateLineItem(draft_order_id, line_id, {
+ *       medusa.admin.draftOrders.updateLineItem(draftOrderId, lineId, {
  *         quantity: 1
  *       })
  *       .then(({ draft_order }) => {
@@ -45,9 +45,9 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "quantity": 1
  *       }'
@@ -151,13 +151,13 @@ export default async (req, res) => {
  * type: object
  * properties:
  *   unit_price:
- *     description: The potential custom price of the item.
+ *     description: The custom price of the line item. If a `variant_id` is supplied, the price provided here will override the variant's price.
  *     type: integer
  *   title:
- *     description: The potential custom title of the item.
+ *     description: The title of the line item if `variant_id` is not provided.
  *     type: string
  *   quantity:
- *     description: The quantity of the Line Item.
+ *     description: The quantity of the line item.
  *     type: integer
  *   metadata:
  *     description: The optional key-value map with additional details about the Line Item.

packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts

@@ -9,7 +9,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/gift-cards
  * operationId: "PostGiftCards"
  * summary: "Create a Gift Card"
- * description: "Creates a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region."
+ * description: "Create a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -34,9 +34,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/gift-cards' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/gift-cards' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "region_id": "{region_id}"
  *       }'
@@ -97,11 +97,11 @@ export default async (req, res) => {
  *     description: The value (excluding VAT) that the Gift Card should represent.
  *   is_disabled:
  *     type: boolean
- *     description: Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.
+ *     description: Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers.
  *   ends_at:
  *     type: string
  *     format: date-time
- *     description: The time at which the Gift Card should no longer be available.
+ *     description: The date and time at which the Gift Card should no longer be available.
  *   region_id:
  *     description: The ID of the Region in which the Gift Card can be used.
  *     type: string

packages/medusa/src/api/routes/admin/gift-cards/delete-gift-card.ts

@@ -4,7 +4,7 @@ import { EntityManager } from "typeorm"
  * @oas [delete] /admin/gift-cards/{id}
  * operationId: "DeleteGiftCardsGiftCard"
  * summary: "Delete a Gift Card"
- * description: "Deletes a Gift Card"
+ * description: "Delete a Gift Card. Once deleted, it can't be used by customers."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Gift Card to delete.
@@ -17,15 +17,15 @@ import { EntityManager } from "typeorm"
  *       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.giftCards.delete(gift_card_id)
+ *       medusa.admin.giftCards.delete(giftCardId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/gift-cards/get-gift-card.ts

@@ -4,7 +4,7 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  * @oas [get] /admin/gift-cards/{id}
  * operationId: "GetGiftCardsGiftCard"
  * summary: "Get a Gift Card"
- * description: "Retrieves a Gift Card."
+ * description: "Retrieve a Gift Card's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Gift Card.
@@ -17,15 +17,15 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  *       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.giftCards.retrieve(gift_card_id)
+ *       medusa.admin.giftCards.retrieve(giftCardId)
  *       .then(({ gift_card }) => {
  *         console.log(gift_card.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/gift-cards/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/gift-cards/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/gift-cards/index.ts

@@ -71,6 +71,7 @@ export const defaultAdminGiftCardRelations = ["region", "order"]
  *   - gift_card
  * properties:
  *   gift_card:
+ *     description: "A gift card's details."
  *     $ref: "#/components/schemas/GiftCard"
  */
 export type AdminGiftCardsRes = {
@@ -94,7 +95,7 @@ export type AdminGiftCardsRes = {
  *     default: gift-card
  *   deleted:
  *     type: boolean
- *     description: Whether the gift card was deleted successfully or not.
+ *     description: Whether the gift card was deleted successfully.
  *     default: true
  */
 export type AdminGiftCardsDeleteRes = DeleteResponse
@@ -125,7 +126,7 @@ export type AdminGiftCardsDeleteRes = DeleteResponse
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of gift cards skipped when retrieving the gift cards.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/gift-cards/list-gift-cards.ts

@@ -10,12 +10,12 @@ import { isDefined } from "medusa-core-utils"
  * @oas [get] /admin/gift-cards
  * operationId: "GetGiftCards"
  * summary: "List Gift Cards"
- * description: "Retrieves a list of Gift Cards."
+ * description: "Retrieve a list of Gift Cards. The gift cards can be filtered by fields such as `q`. The gift cards can also paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) offset=0 {number} The number of items to skip before the results.
- *   - (query) limit=50 {number} Limit the number of items returned.
- *   - (query) q {string} a search term to search by code or display ID
+ *   - (query) offset=0 {number} The number of gift cards to skip when retrieving the gift cards.
+ *   - (query) limit=50 {number} Limit the number of gift cards returned.
+ *   - (query) q {string} a term to search gift cards' code or display ID
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetGiftCardsParams
@@ -33,8 +33,8 @@ import { isDefined } from "medusa-core-utils"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/gift-cards' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/gift-cards' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts

@@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/gift-cards/{id}
  * operationId: "PostGiftCardsGiftCard"
  * summary: "Update a Gift Card"
- * description: "Update a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region."
+ * description: "Update a Gift Card's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Gift Card.
@@ -28,7 +28,7 @@ import { validator } from "../../../../utils/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.giftCards.update(gift_card_id, {
+ *       medusa.admin.giftCards.update(giftCardId, {
  *         region_id
  *       })
  *       .then(({ gift_card }) => {
@@ -37,9 +37,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/gift-cards/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/gift-cards/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "region_id": "{region_id}"
  *       }'
@@ -99,11 +99,11 @@ export default async (req, res) => {
  *     description: The value (excluding VAT) that the Gift Card should represent.
  *   is_disabled:
  *     type: boolean
- *     description: Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.
+ *     description: Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers.
  *   ends_at:
  *     type: string
  *     format: date-time
- *     description: The time at which the Gift Card should no longer be available.
+ *     description: The date and time at which the Gift Card should no longer be available.
  *   region_id:
  *     description: The ID of the Region in which the Gift Card can be used.
  *     type: string

packages/medusa/src/api/routes/admin/inventory-items/create-inventory-item.ts

@@ -15,11 +15,11 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/inventory-items
  * operationId: "PostInventoryItems"
  * summary: "Create an Inventory Item"
- * description: "Creates an Inventory Item."
+ * description: "Create an Inventory Item."
  * x-authenticated: true
  * parameters:
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned inventory item.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory item.
  * requestBody:
  *   content:
  *     application/json:
@@ -36,7 +36,7 @@ import { validator } from "../../../../utils/validator"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.inventoryItems.create({
- *         variant_id: 'variant_123',
+ *         variant_id: "variant_123",
  *       })
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
@@ -44,9 +44,9 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/inventory-items' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/inventory-items' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "variant_id": "variant_123",
  *       }'
@@ -132,7 +132,7 @@ export default async (req, res) => {
  * type: object
  * properties:
  *   sku:
- *     description: The unique SKU for the Product Variant.
+ *     description: The unique SKU of the associated Product Variant.
  *     type: string
  *   ean:
  *     description: The EAN number of the item.
@@ -144,39 +144,39 @@ export default async (req, res) => {
  *     description: A generic GTIN field for the Product Variant.
  *     type: string
  *   hs_code:
- *     description: The Harmonized System code for the Product Variant.
+ *     description: The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.
  *     type: string
  *   inventory_quantity:
- *     description: The amount of stock kept for the Product Variant.
+ *     description: The amount of stock kept of the associated Product Variant.
  *     type: integer
  *     default: 0
  *   allow_backorder:
- *     description: Whether the Product Variant can be purchased when out of stock.
+ *     description: Whether the associated Product Variant can be purchased when out of stock.
  *     type: boolean
  *   manage_inventory:
- *     description: Whether Medusa should keep track of the inventory for this Product Variant.
+ *     description: Whether Medusa should keep track of the inventory for the associated Product Variant.
  *     type: boolean
  *     default: true
  *   weight:
- *     description: The wieght of the Product Variant.
+ *     description: The weight of the Inventory Item. May be used in shipping rate calculations.
  *     type: number
  *   length:
- *     description: The length of the Product Variant.
+ *     description: The length of the Inventory Item. May be used in shipping rate calculations.
  *     type: number
  *   height:
- *     description: The height of the Product Variant.
+ *     description: The height of the Inventory Item. May be used in shipping rate calculations.
  *     type: number
  *   width:
- *     description: The width of the Product Variant.
+ *     description: The width of the Inventory Item. May be used in shipping rate calculations.
  *     type: number
  *   origin_country:
- *     description: The country of origin of the Product Variant.
+ *     description: The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
  *     type: string
  *   mid_code:
- *     description: The Manufacturer Identification code for the Product Variant.
+ *     description: The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.
  *     type: string
  *   material:
- *     description: The material composition of the Product Variant.
+ *     description: The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
  *     type: string
  *   metadata:
  *     description: An optional set of key-value pairs with additional information.

packages/medusa/src/api/routes/admin/inventory-items/create-location-level.ts

@@ -7,12 +7,12 @@ import { FindParams } from "../../../../types/common"
  * @oas [post] /admin/inventory-items/{id}/location-levels
  * operationId: "PostInventoryItemsInventoryItemLocationLevels"
  * summary: "Create an Inventory Level"
- * description: "Creates an Inventory Level for a given Inventory Item."
+ * description: "Create an Inventory Level for a given Inventory Item."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Inventory Item.
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned inventory item.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory item.
  * requestBody:
  *   content:
  *     application/json:
@@ -29,7 +29,7 @@ import { FindParams } from "../../../../types/common"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.inventoryItems.createLocationLevel(inventoryItemId, {
- *         location_id: 'sloc_123',
+ *         location_id: "sloc_123",
  *         stocked_quantity: 10,
  *       })
  *       .then(({ inventory_item }) => {
@@ -38,9 +38,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "location_id": "sloc_123",
  *           "stocked_quantity": 10
@@ -111,13 +111,13 @@ export default async (req: Request, res: Response) => {
  *   - stocked_quantity
  * properties:
  *   location_id:
- *     description: the item location ID
+ *     description: the ID of the stock location
  *     type: string
  *   stocked_quantity:
- *     description: the stock quantity of an inventory item at the given location ID
+ *     description: the stock quantity of the inventory item at this location
  *     type: number
  *   incoming_quantity:
- *     description: the incoming stock quantity of an inventory item at the given location ID
+ *     description: the incoming stock quantity of the inventory item at this location
  *     type: number
  */
 export class AdminPostInventoryItemsItemLocationLevelsReq {

packages/medusa/src/api/routes/admin/inventory-items/delete-inventory-item.ts

@@ -7,7 +7,7 @@ import { ProductVariantInventoryService } from "../../../../services"
  * @oas [delete] /admin/inventory-items/{id}
  * operationId: "DeleteInventoryItemsInventoryItem"
  * summary: "Delete an Inventory Item"
- * description: "Delete an Inventory Item"
+ * description: "Delete an Inventory Item. This does not delete the associated product variant."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Inventory Item to delete.
@@ -27,8 +27,8 @@ import { ProductVariantInventoryService } from "../../../../services"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/inventory-items/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/inventory-items/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/inventory-items/delete-location-level.ts

@@ -28,8 +28,8 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/inventory-items/get-inventory-item.ts

@@ -7,12 +7,12 @@ import { joinLevels } from "./utils/join-levels"
  * @oas [get] /admin/inventory-items/{id}
  * operationId: "GetInventoryItemsInventoryItem"
  * summary: "Get an Inventory Item"
- * description: "Retrieves an Inventory Item."
+ * description: "Retrieve an Inventory Item's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Inventory Item.
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned inventory item.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory item.
  * x-codegen:
  *   method: retrieve
  *   queryParams: AdminGetInventoryItemsItemParams
@@ -30,8 +30,8 @@ import { joinLevels } from "./utils/join-levels"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/inventory-items/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/inventory-items/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/inventory-items/index.ts

@@ -170,6 +170,7 @@ export const defaultAdminInventoryItemRelations = []
  *   - inventory_item
  * properties:
  *   inventory_item:
+ *     description: Inventory Item details
  *     $ref: "#/components/schemas/InventoryItemDTO"
  */
 export type AdminInventoryItemsRes = {
@@ -209,6 +210,7 @@ export type AdminInventoryItemsDeleteRes = DeleteResponse
  * properties:
  *   inventory_items:
  *     type: array
+ *     description: an array of Inventory Item details
  *     items:
  *       $ref: "#/components/schemas/InventoryItemDTO"
  *   count:
@@ -216,7 +218,7 @@ export type AdminInventoryItemsDeleteRes = DeleteResponse
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of inventory items skipped when retrieving the inventory items.
  *   limit:
  *     type: integer
  *     description: The number of items per page
@@ -237,10 +239,12 @@ export type AdminInventoryItemsListRes = PaginatedResponse & {
  *     properties:
  *       location_levels:
  *         type: array
+ *         description: An array of location level details
  *         items:
  *           $ref: "#/components/schemas/InventoryLevelDTO"
  *       variants:
  *         type: array
+ *         description: An array of product variant details
  *         items:
  *           $ref: "#/components/schemas/ProductVariant"
  *       stocked_quantity:
@@ -268,6 +272,7 @@ export type DecoratedInventoryItemDTO = InventoryItemDTO & {
  * properties:
  *   inventory_items:
  *     type: array
+ *     description: an array of Inventory Item details
  *     items:
  *       $ref: "#/components/schemas/DecoratedInventoryItemDTO"
  *   count:
@@ -275,7 +280,7 @@ export type DecoratedInventoryItemDTO = InventoryItemDTO & {
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of inventory items skipped when retrieving the inventory items.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/inventory-items/list-inventory-items.ts

@@ -23,34 +23,46 @@ import { Transform } from "class-transformer"
  * @oas [get] /admin/inventory-items
  * operationId: "GetInventoryItems"
  * summary: "List Inventory Items"
- * description: "Lists inventory items with the ability to apply filters or search queries on them."
+ * description: "Retrieve a list of inventory items. The inventory items can be filtered by fields such as `q` or `location_id`. The inventory items can also be paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) offset=0 {integer} How many inventory items to skip in the result.
+ *   - (query) offset=0 {integer} The number of inventory items to skip when retrieving the inventory items.
  *   - (query) limit=20 {integer} Limit the number of inventory items returned.
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
- *   - (query) q {string} Query used for searching product inventory items and their properties.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in each returned inventory item.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory item.
+ *   - (query) q {string} term to search inventory item's sku, title, and description.
  *   - in: query
  *     name: location_id
  *     style: form
  *     explode: false
- *     description: Locations ids to search for.
+ *     description: Filter by location IDs.
  *     schema:
  *       type: array
  *       items:
  *         type: string
- *   - (query) id {string} id to search for.
- *   - (query) sku {string} sku to search for.
- *   - (query) origin_country {string} origin_country to search for.
- *   - (query) mid_code {string} mid_code to search for.
- *   - (query) material {string} material to search for.
- *   - (query) hs_code {string} hs_code to search for.
- *   - (query) weight {string} weight to search for.
- *   - (query) length {string} length to search for.
- *   - (query) height {string} height to search for.
- *   - (query) width {string} width to search for.
- *   - (query) requires_shipping {string} requires_shipping to search for.
+ *   - in: query
+ *     name: id
+ *     style: form
+ *     explode: false
+ *     description: Filter by the inventory ID
+ *     schema:
+ *       oneOf:
+ *         - type: string
+ *           description: inventory ID
+ *         - type: array
+ *           description: an array of inventory IDs
+ *           items:
+ *             type: string
+ *   - (query) sku {string} Filter by SKU
+ *   - (query) origin_country {string} Filter by origin country
+ *   - (query) mid_code {string} Filter by MID code
+ *   - (query) material {string} Filter by material
+ *   - (query) hs_code {string} Filter by HS Code
+ *   - (query) weight {string} Filter by weight
+ *   - (query) length {string} Filter by length
+ *   - (query) height {string} Filter by height
+ *   - (query) width {string} Filter by width
+ *   - (query) requires_shipping {string} Filter by whether the item requires shipping
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetInventoryItemsParams
@@ -68,8 +80,8 @@ import { Transform } from "class-transformer"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/inventory-items' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/inventory-items' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/inventory-items/list-location-levels.ts

@@ -8,22 +8,22 @@ import { IsType } from "../../../../utils/validators/is-type"
 /**
  * @oas [get] /admin/inventory-items/{id}/location-levels
  * operationId: "GetInventoryItemsInventoryItemLocationLevels"
- * summary: "List Inventory Levels"
- * description: "Lists inventory levels of an inventory item."
+ * summary: "List Inventory Level"
+ * description: "Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`. The inventory levels can also be paginated."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The ID of the Inventory Item.
+ *   - (path) id=* {string} The ID of the Inventory Item the locations are associated with.
  *   - in: query
  *     name: location_id
  *     style: form
  *     explode: false
- *     description: Locations ids to search for.
+ *     description: Filter by location IDs.
  *     schema:
  *       type: array
  *       items:
  *         type: string
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned inventory levels.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory levels.
  * x-codegen:
  *   method: listLocationLevels
  *   queryParams: AdminGetInventoryItemsItemLocationLevelsParams
@@ -41,8 +41,8 @@ import { IsType } from "../../../../utils/validators/is-type"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/inventory-items/update-inventory-item.ts

@@ -9,12 +9,12 @@ import { IInventoryService } from "@medusajs/types"
  * @oas [post] /admin/inventory-items/{id}
  * operationId: "PostInventoryItemsInventoryItem"
  * summary: "Update an Inventory Item"
- * description: "Updates an Inventory Item."
+ * description: "Update an Inventory Item's details."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Inventory Item.
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned inventory level.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory level.
  * requestBody:
  *   content:
  *     application/json:
@@ -39,9 +39,9 @@ import { IInventoryService } from "@medusajs/types"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "origin_country": "US"
  *       }'

packages/medusa/src/api/routes/admin/inventory-items/update-location-level.ts

@@ -8,13 +8,13 @@ import { FindParams } from "../../../../types/common"
  * @oas [post] /admin/inventory-items/{id}/location-levels/{location_id}
  * operationId: "PostInventoryItemsInventoryItemLocationLevelsLocationLevel"
  * summary: "Update an Inventory Level"
- * description: "Updates an Inventory Level for a given Inventory Item."
+ * description: "Update an Inventory Level's details for a given Inventory Item."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The ID of the Inventory Item.
- *   - (path) location_id=* {string} The ID of the Location.
- *   - (query) expand {string} Comma separated list of relations to include in the results.
- *   - (query) fields {string} Comma separated list of fields to include in the results.
+ *   - (path) id=* {string} The ID of the Inventory Item that the location is associated with.
+ *   - (path) location_id=* {string} The ID of the Location to update.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in the returned inventory level.
+ *   - (query) fields {string} Comma-separated fields that should be included in the returned inventory level.
  * requestBody:
  *   content:
  *     application/json:
@@ -39,9 +39,9 @@ import { FindParams } from "../../../../types/common"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "stocked_quantity": 15
  *       }'

packages/medusa/src/api/routes/admin/invites/accept-invite.ts

@@ -9,7 +9,8 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/invites/accept
  * operationId: "PostInvitesInviteAccept"
  * summary: "Accept an Invite"
- * description: "Accepts an Invite and creates a corresponding user"
+ * description: "Accept an Invite. This will also delete the invite and create a new user that can log in and perform admin functionalities. The user will have the email associated with the invite, and the password
+ *  provided in the request body."
  * requestBody:
  *   content:
  *     application/json:
@@ -27,9 +28,9 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.invites.accept({
  *         token,
  *         user: {
- *           first_name: 'Brigitte',
- *           last_name: 'Collier',
- *           password: 'supersecret'
+ *           first_name: "Brigitte",
+ *           last_name: "Collier",
+ *           password: "supersecret"
  *         }
  *       })
  *       .then(() => {
@@ -41,9 +42,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/invites/accept' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/invites/accept' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "token": "{token}",
  *           "user": {
@@ -107,10 +108,10 @@ export class AdminPostInvitesInviteAcceptUserReq {
  *   - user
  * properties:
  *   token:
- *     description: "The invite token provided by the admin."
+ *     description: "The token of the invite to accept. This is a unique token generated when the invite was created or resent."
  *     type: string
  *   user:
- *     description: "The User to create."
+ *     description: "The details of the user to create."
  *     type: object
  *     required:
  *       - first_name
@@ -124,7 +125,7 @@ export class AdminPostInvitesInviteAcceptUserReq {
  *         type: string
  *         description: the last name of the User
  *       password:
- *         description: The desired password for the User
+ *         description: The password for the User
  *         type: string
  *         format: password
  */

packages/medusa/src/api/routes/admin/invites/create-invite.ts

@@ -9,7 +9,8 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/invites
  * operationId: "PostInvites"
  * summary: "Create an Invite"
- * description: "Creates an Invite and triggers an 'invite' created event"
+ * description: "Create an Invite. This will generate a token associated with the invite and trigger an `invite.created` event. If you have a Notification Provider installed that handles this
+ *  event, a notification should be sent to the email associated with the invite to allow them to accept the invite."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -38,9 +39,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/invites' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/invites' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "user": "user@example.com",
  *           "role": "admin"
@@ -89,11 +90,11 @@ export default async (req, res) => {
  *   - role
  * properties:
  *   user:
- *     description: "The email for the user to be created."
+ *     description: "The email associated with the invite. Once the invite is accepted, the email will be associated with the created user."
  *     type: string
  *     format: email
  *   role:
- *     description: "The role of the user to be created."
+ *     description: "The role of the user to be created. This does not actually change the privileges of the user that is eventually created."
  *     type: string
  *     enum: [admin, member, developer]
  */

packages/medusa/src/api/routes/admin/invites/delete-invite.ts

@@ -5,7 +5,7 @@ import InviteService from "../../../../services/invite"
  * @oas [delete] /admin/invites/{invite_id}
  * operationId: "DeleteInvitesInvite"
  * summary: "Delete an Invite"
- * description: "Deletes an Invite"
+ * description: "Delete an Invite. Only invites that weren't accepted can be deleted."
  * x-authenticated: true
  * parameters:
  *   - (path) invite_id=* {string} The ID of the Invite
@@ -18,15 +18,15 @@ import InviteService from "../../../../services/invite"
  *       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.invites.delete(invite_id)
+ *       medusa.admin.invites.delete(inviteId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/invites/index.ts

@@ -49,7 +49,7 @@ export default (app) => {
  *     default: invite
  *   deleted:
  *     type: boolean
- *     description: Whether or not the Invite was deleted.
+ *     description: Whether or not the invite was deleted.
  *     default: true
  */
 export type AdminInviteDeleteRes = DeleteResponse
@@ -62,6 +62,7 @@ export type AdminInviteDeleteRes = DeleteResponse
  * properties:
  *   invites:
  *     type: array
+ *     description: An array of invites
  *     items:
  *       $ref: "#/components/schemas/Invite"
  */

packages/medusa/src/api/routes/admin/invites/list-invites.ts

@@ -4,7 +4,7 @@ import InviteService from "../../../../services/invite"
  * @oas [get] /admin/invites
  * operationId: "GetInvites"
  * summary: "Lists Invites"
- * description: "Lists all Invites"
+ * description: "Retrieve a list of invites."
  * x-authenticated: true
  * x-codegen:
  *   method: list
@@ -22,8 +22,8 @@ import InviteService from "../../../../services/invite"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/invites' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/invites' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/invites/resend-invite.ts

@@ -5,7 +5,8 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/invites/{invite_id}/resend
  * operationId: "PostInvitesInviteResend"
  * summary: "Resend an Invite"
- * description: "Resends an Invite by triggering the 'invite' created event again"
+ * description: "Resend an Invite. This renews the expiry date by 7 days and generates a new token for the invite. It also triggers the `invite.created` event, so if you have a Notification Provider installed that handles this
+ *  event, a notification should be sent to the email associated with the invite to allow them to accept the invite."
  * x-authenticated: true
  * parameters:
  *   - (path) invite_id=* {string} The ID of the Invite
@@ -18,7 +19,7 @@ import { EntityManager } from "typeorm"
  *       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.invites.resend(invite_id)
+ *       medusa.admin.invites.resend(inviteId)
  *       .then(() => {
  *         // successful
  *       })
@@ -28,8 +29,8 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/notes/create-note.ts

@@ -7,8 +7,8 @@ import { EntityManager } from "typeorm"
 /**
  * @oas [post] /admin/notes
  * operationId: "PostNotes"
- * summary: "Creates a Note"
- * description: "Creates a Note which can be associated with any resource as required."
+ * summary: "Create a Note"
+ * description: "Create a Note which can be associated with any resource."
  * x-authenticated: true
  * requestBody:
  *  content:
@@ -26,8 +26,8 @@ import { EntityManager } from "typeorm"
  *       // must be previously logged in or use api token
  *       medusa.admin.notes.create({
  *         resource_id,
- *         resource_type: 'order',
- *         value: 'We delivered this order'
+ *         resource_type: "order",
+ *         value: "We delivered this order"
  *       })
  *       .then(({ note }) => {
  *         console.log(note.id);
@@ -35,9 +35,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/notes' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/notes' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "resource_id": "{resource_id}",
  *           "resource_type": "order",
@@ -99,10 +99,10 @@ export default async (req, res) => {
  * properties:
  *   resource_id:
  *     type: string
- *     description: The ID of the resource which the Note relates to.
+ *     description: The ID of the resource which the Note relates to. For example, an order ID.
  *   resource_type:
  *     type: string
- *     description: The type of resource which the Note relates to.
+ *     description: The type of resource which the Note relates to. For example, `order`.
  *   value:
  *     type: string
  *     description: The content of the Note to create.

packages/medusa/src/api/routes/admin/notes/delete-note.ts

@@ -5,7 +5,7 @@ import NoteService from "../../../../services/note"
  * @oas [delete] /admin/notes/{id}
  * operationId: "DeleteNotesNote"
  * summary: "Delete a Note"
- * description: "Deletes a Note."
+ * description: "Delete a Note."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Note to delete.
@@ -18,15 +18,15 @@ import NoteService from "../../../../services/note"
  *       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.notes.delete(note_id)
+ *       medusa.admin.notes.delete(noteId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request DELETE 'https://medusa-url.com/admin/notes/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X DELETE 'https://medusa-url.com/admin/notes/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/notes/get-note.ts

@@ -4,10 +4,10 @@ import NoteService from "../../../../services/note"
  * @oas [get] /admin/notes/{id}
  * operationId: "GetNotesNote"
  * summary: "Get a Note"
- * description: "Retrieves a single note using its id"
+ * description: "Retrieve a note's details."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The ID of the note to retrieve.
+ *   - (path) id=* {string} The ID of the note.
  * x-codegen:
  *   method: retrieve
  * x-codeSamples:
@@ -17,15 +17,15 @@ import NoteService from "../../../../services/note"
  *       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.notes.retrieve(note_id)
+ *       medusa.admin.notes.retrieve(noteId)
  *       .then(({ note }) => {
  *         console.log(note.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/notes/{id}' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/notes/{id}' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/notes/index.ts

@@ -29,6 +29,7 @@ export default (app) => {
  *   - note
  * properties:
  *   note:
+ *     description: Note details.
  *     $ref: "#/components/schemas/Note"
  */
 export type AdminNotesRes = {
@@ -68,6 +69,7 @@ export type AdminNotesDeleteRes = DeleteResponse
  * properties:
  *   notes:
  *     type: array
+ *     description: An array of notes
  *     items:
  *       $ref: "#/components/schemas/Note"
  *   count:
@@ -75,7 +77,7 @@ export type AdminNotesDeleteRes = DeleteResponse
  *     description: The total number of items available
  *   offset:
  *     type: integer
- *     description: The number of items skipped before these items
+ *     description: The number of notes skipped when retrieving the notes.
  *   limit:
  *     type: integer
  *     description: The number of items per page

packages/medusa/src/api/routes/admin/notes/list-notes.ts

@@ -10,11 +10,11 @@ import { validator } from "../../../../utils/validator"
  * operationId: "GetNotes"
  * summary: "List Notes"
  * x-authenticated: true
- * description: "Retrieves a list of notes"
+ * description: "Retrieve a list of notes. The notes can be filtered by fields such as `resource_id`. The notes can also be paginated."
  * parameters:
- *   - (query) limit=50 {number} The number of notes to get
- *   - (query) offset=0 {number} The offset at which to get notes
- *   - (query) resource_id {string} The ID which the notes belongs to
+ *   - (query) limit=50 {number} Limit the number of notes returned.
+ *   - (query) offset=0 {number} The number of notes to skip when retrieving the notes.
+ *   - (query) resource_id {string} Filter by resource ID
  * x-codegen:
  *   method: list
  *   queryParams: AdminGetNotesParams
@@ -32,8 +32,8 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/notes' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/notes' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/notes/update-note.ts

@@ -8,9 +8,9 @@ import { EntityManager } from "typeorm"
  * operationId: "PostNotesNote"
  * summary: "Update a Note"
  * x-authenticated: true
- * description: "Updates a Note associated with some resource"
+ * description: "Update a Note's details.'"
  * parameters:
- *   - (path) id=* {string} The ID of the Note to update
+ *   - (path) id=* {string} The ID of the Note
  * requestBody:
  *  content:
  *    application/json:
@@ -25,8 +25,8 @@ import { EntityManager } from "typeorm"
  *       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.notes.update(note_id, {
- *        value: 'We delivered this order'
+ *       medusa.admin.notes.update(noteId, {
+ *        value: "We delivered this order"
  *       })
  *       .then(({ note }) => {
  *         console.log(note.id);
@@ -34,9 +34,9 @@ import { EntityManager } from "typeorm"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/notes/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/notes/{id}' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{
  *           "value": "We delivered this order"
  *       }'
@@ -89,7 +89,7 @@ export default async (req, res) => {
  * properties:
  *   value:
  *     type: string
- *     description: The updated description of the Note.
+ *     description: The description of the Note.
  */
 export class AdminPostNotesNoteReq {
   @IsString()

packages/medusa/src/api/routes/admin/notifications/index.ts

@@ -49,6 +49,7 @@ export const defaultAdminNotificationsFields = [
  * properties:
  *   notifications:
  *     type: array
+ *     description: an array of notifications
  *     items:
  *       $ref: "#/components/schemas/Notification"
  *   count:
@@ -56,7 +57,7 @@ export const defaultAdminNotificationsFields = [
  *     description: The total number of notifications
  *   offset:
  *     type: integer
- *     description: The number of notifications skipped before these notifications
+ *     description: The number of notifications skipped when retrieving the notifications.
  *   limit:
  *     type: integer
  *     description: The number of notifications per page
@@ -76,6 +77,7 @@ export type AdminNotificationsListRes = PaginatedResponse & {
  *   - notification
  * properties:
  *   notification:
+ *     description: Notification details
  *     $ref: "#/components/schemas/Notification"
  */
 export type AdminNotificationsRes = {

packages/medusa/src/api/routes/admin/notifications/list-notifications.ts

@@ -15,17 +15,17 @@ import { validator } from "../../../../utils/validator"
  * @oas [get] /admin/notifications
  * operationId: "GetNotifications"
  * summary: "List Notifications"
- * description: "Retrieves a list of Notifications."
+ * description: "Retrieve a list of notifications. The notifications can be filtered by fields such as `event_name` or `resource_type`. The notifications can also be paginated."
  * x-authenticated: true
  * parameters:
- *   - (query) offset=0 {integer} The number of notifications to skip before starting to collect the notifications set
- *   - (query) limit=50 {integer} The number of notifications to return
- *   - (query) fields {string} Comma separated fields to include in the result set
- *   - (query) expand {string} Comma separated fields to populate
- *   - (query) event_name {string} The name of the event that the notification was sent for.
- *   - (query) resource_type {string} The type of resource that the Notification refers to.
- *   - (query) resource_id {string} The ID of the resource that the Notification refers to.
- *   - (query) to {string} The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id
+ *   - (query) offset=0 {integer} The number of inventory items to skip when retrieving the inventory items.
+ *   - (query) limit=50 {integer} Limit the number of notifications returned.
+ *   - (query) fields {string} Comma-separated fields that should be included in each returned notification.
+ *   - (query) expand {string} Comma-separated relations that should be expanded in each returned notification.
+ *   - (query) event_name {string} Filter by the name of the event that triggered sending this notification.
+ *   - (query) resource_type {string} Filter by the resource type.
+ *   - (query) resource_id {string} Filter by the resource ID.
+ *   - (query) to {string} Filter by the address that the Notification was sent to. This will usually be an email address, but it can also represent other addresses such as a chat bot user id.
  *   - (query) include_resends {string} A boolean indicating whether the result set should include resent notifications or not
  * x-codegen:
  *   method: list
@@ -44,8 +44,8 @@ import { validator } from "../../../../utils/validator"
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request GET 'https://medusa-url.com/admin/notifications' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl 'https://medusa-url.com/admin/notifications' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/notifications/resend-notification.ts

@@ -13,7 +13,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/notifications/{id}/resend
  * operationId: "PostNotificationsNotificationResend"
  * summary: "Resend Notification"
- * description: "Resends a previously sent notifications, with the same data but optionally to a different address"
+ * description: "Resend a previously sent notifications, with the same data but optionally to a different address."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Notification
@@ -31,15 +31,15 @@ import { validator } from "../../../../utils/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.notifications.resend(notification_id)
+ *       medusa.admin.notifications.resend(notificationId)
  *       .then(({ notification }) => {
  *         console.log(notification.id);
  *       });
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/notifications/{id}/resend' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/notifications/{id}/resend' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []
@@ -103,7 +103,7 @@ export default async (req, res) => {
  * type: object
  * properties:
  *   to:
- *     description: "A new address or user identifier that the Notification should be sent to"
+ *     description: "A new address or user identifier that the Notification should be sent to. If not provided, the previous `to` field of the notification will be used."
  *     type: string
  */
 export class AdminPostNotificationsNotificationResendReq {

packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts

@@ -12,7 +12,8 @@ import {
  * @oas [post] /admin/order-edits/{id}/items
  * operationId: "PostOrderEditsEditLineItems"
  * summary: "Add a Line Item"
- * description: "Create an OrderEdit LineItem."
+ * description: "Create a line item change in the order edit that indicates adding an item in the original order. The item will not be added to the original order until the order edit is
+ *  confirmed."
  * parameters:
  *   - (path) id=* {string} The ID of the Order Edit.
  * requestBody:
@@ -30,7 +31,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.addLineItem(order_edit_id, {
+ *       medusa.admin.orderEdits.addLineItem(orderEditId, {
  *         variant_id,
  *         quantity
  *       })
@@ -40,9 +41,9 @@ import {
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/items' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", "quantity": 3 }'
  * security:
  *   - api_token: []
@@ -106,10 +107,10 @@ export default async (req: Request, res: Response) => {
  *   - quantity
  * properties:
  *   variant_id:
- *     description: The ID of the variant ID to add
+ *     description: The ID of the product variant associated with the item.
  *     type: string
  *   quantity:
- *     description: The quantity to add
+ *     description: The quantity of the item.
  *     type: number
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.

packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts

@@ -9,8 +9,8 @@ import {
 /**
  * @oas [post] /admin/order-edits/{id}/cancel
  * operationId: "PostOrderEditsOrderEditCancel"
- * summary: "Cancel an OrderEdit"
- * description: "Cancels an OrderEdit."
+ * summary: "Cancel an Order Edit"
+ * description: "Cancel an OrderEdit."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the OrderEdit.
@@ -23,15 +23,15 @@ 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.cancel(order_edit_id)
+ *       medusa.admin.orderEdits.cancel(orderEditId)
  *         .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' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts

@@ -9,8 +9,8 @@ import {
 /**
  * @oas [post] /admin/order-edits/{id}/confirm
  * operationId: "PostOrderEditsOrderEditConfirm"
- * summary: "Confirms an OrderEdit"
- * description: "Confirms an OrderEdit."
+ * summary: "Confirm an OrderEdit"
+ * description: "Confirm an Order Edit. This will reflect the changes in the order edit on the associated order."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the order edit.
@@ -23,15 +23,15 @@ 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.confirm(order_edit_id)
+ *       medusa.admin.orderEdits.confirm(orderEditId)
  *         .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' \
- *       --header 'Authorization: Bearer {api_token}'
+ *       curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \
+ *       -H 'Authorization: Bearer {api_token}'
  * security:
  *   - api_token: []
  *   - cookie_auth: []

packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts

@@ -11,7 +11,7 @@ import {
  * @oas [post] /admin/order-edits
  * operationId: "PostOrderEdits"
  * summary: "Create an OrderEdit"
- * description: "Creates an OrderEdit."
+ * description: "Create an Order Edit."
  * requestBody:
  *   content:
  *     application/json:
@@ -27,16 +27,16 @@ 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.create({ order_id })
+ *       medusa.admin.orderEdits.create({ orderId })
  *         .then(({ order_edit }) => {
  *           console.log(order_edit.id)
  *         })
  *   - lang: Shell
  *     label: cURL
  *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/order-edits' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
+ *       curl -X POST 'https://medusa-url.com/admin/order-edits' \
+ *       -H 'Authorization: Bearer {api_token}' \
+ *       -H 'Content-Type: application/json' \
  *       --data-raw '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }'
  * security:
  *   - api_token: []
@@ -99,7 +99,7 @@ export default async (req: Request, res: Response) => {
  *     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.
+ *     description: An optional note to associate with the order edit.
  *     type: string
  */
 export class AdminPostOrderEditsReq {