chore(docs): Refactor API Reference (#1883)

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

@@ -1,8 +1,10 @@
 import { IsNotEmpty, IsString } from "class-validator"
+
 import { OauthService } from "../../../../services"
 import { validator } from "../../../../utils/validator"
+
 /**
- * @oas [post] /apps
+ * @oas [post] /apps/authorizations
  * operationId: "PostApps"
  * summary: "Generates a token for an application."
  * description: "Generates a token for an application."
@@ -26,7 +28,7 @@ import { validator } from "../../../../utils/validator"
  *             type: string
  *             description: The code for the generated token.
  * tags:
- *   - Apps
+ *   - App
  * responses:
  *  "200":
  *    description: OK

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

@@ -7,7 +7,7 @@ import { OauthService } from "../../../../services"
  * description: "Retrieve a list of applications."
  * x-authenticated: true
  * tags:
- *   - Apps
+ *   - App
  * responses:
  *  "200":
  *    description: OK
@@ -15,8 +15,10 @@ import { OauthService } from "../../../../services"
  *      application/json:
  *        schema:
  *          properties:
- *            collection:
- *              $ref: "#/components/schemas/OAuth"
+ *            apps:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/OAuth"
  */
 export default async (req, res) => {
   const oauthService: OauthService = req.scope.resolve("oauthService")

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

@@ -1,10 +1,11 @@
+import { IsEmail, IsNotEmpty, IsString } from "class-validator"
+
+import AuthService from "../../../../services/auth"
+import { EntityManager } from "typeorm";
+import { MedusaError } from "medusa-core-utils"
 import _ from "lodash"
 import jwt from "jsonwebtoken"
 import { validator } from "../../../../utils/validator"
-import { IsEmail, IsNotEmpty, IsString } from "class-validator"
-import AuthService from "../../../../services/auth"
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm";
 
 /**
  * @oas [post] /auth
@@ -15,6 +16,22 @@ import { EntityManager } from "typeorm";
  * parameters:
  *   - (body) email=* {string} The User's email.
  *   - (body) password=* {string} The User's password.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - email
+ *           - password
+ *         properties:
+ *           email:
+ *             type: string
+ *             description: The User's email.
+ *             format: email
+ *           password:
+ *             type: string
+ *             description: The User's password.
+ *             format: password
  * tags:
  *   - Auth
  * responses:
@@ -26,6 +43,8 @@ import { EntityManager } from "typeorm";
  *          properties:
  *            user:
  *              $ref: "#/components/schemas/user"
+ *  "401":
+ *    description: The user doesn't exist or the credentials are incorrect.
  */
 export default async (req, res) => {
   const { projectConfig: { jwt_secret } } = req.scope.resolve('configModule')

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

@@ -1,5 +1,5 @@
 /**
- * @oas [get] /auth
+ * @oas [delete] /auth
  * operationId: "DeleteAuth"
  * summary: "Delete Session"
  * x-authenticated: true

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

@@ -1,5 +1,5 @@
-import _ from "lodash"
 import UserService from "../../../../services/user"
+import _ from "lodash"
 
 /**
  * @oas [get] /auth
@@ -18,6 +18,8 @@ import UserService from "../../../../services/user"
  *          properties:
  *            user:
  *              $ref: "#/components/schemas/user"
+ *  "400":
+ *    description: An error occurred.
  */
 export default async (req, res) => {
   try {

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Marks a batch job as canceled"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the batch job.
+ *   - (path) id=* {string} The ID of the batch job.
  * tags:
  *   - Batch Job
  * responses:

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Confirms that a previously requested batch job should be executed."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the batch job.
+ *   - (path) id=* {string} The ID of the batch job.
  * tags:
  *   - Batch Job
  * responses:
@@ -17,11 +17,10 @@ import { EntityManager } from "typeorm"
  *    content:
  *      application/json:
  *        schema:
- *          properties:x
+ *          properties:
  *            batch_job:
  *              $ref: "#/components/schemas/batch_job"
  */
-
 export default async (req, res) => {
   let batch_job = req.batch_job
 

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

@@ -1,8 +1,9 @@
 import { IsBoolean, IsObject, IsOptional, IsString } from "class-validator"
-import BatchJobService from "../../../../services/batch-job"
-import { validator } from "../../../../utils/validator"
+
 import { BatchJob } from "../../../../models"
+import BatchJobService from "../../../../services/batch-job"
 import { EntityManager } from "typeorm"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /batch-jobs
@@ -10,12 +11,43 @@ import { EntityManager } from "typeorm"
  * summary: "Create a Batch Job"
  * description: "Creates a Batch Job."
  * x-authenticated: true
- * parameters:
- *   - (body) type=* {string} The type of batch job to start.
- *   - (body) context=* {string} Additional infomration regarding the batch to be used for processing.
- *   - (body) dry_run=* {boolean} Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.
+ * requestBody:
+ *   content:
+ *    application/json:
+ *      schema:
+ *        required:
+ *          - type
+ *          - context
+ *        properties:
+ *          type:
+ *            type: string
+ *            description: The type of batch job to start.
+ *            example: product-export
+ *          context:
+ *            type: object
+ *            description: Additional infomration regarding the batch to be used for processing.
+ *            example:
+ *              shape:
+ *                prices:
+ *                  - region: null
+ *                    currency_code: "eur"
+ *                dynamicImageColumnCount: 4
+ *                dynamicOptionColumnCount: 2
+ *              list_config:
+ *                skip: 0
+ *                take: 50
+ *                order:
+ *                  created_at: "DESC"
+ *                relations:
+ *                  - variants
+ *                  - variant.prices
+ *                  - 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.
+ *            default: false
  * tags:
- *   - Customer
+ *   - Batch Job
  * responses:
  *   201:
  *     description: OK

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

@@ -5,7 +5,7 @@
  * description: "Retrieves a Batch Job."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Batch Job
+ *   - (path) id=* {string} The ID of the Batch Job
  * tags:
  *   - Batch Job
  * responses:

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

@@ -1,15 +1,11 @@
+import { IsArray, IsNumber, IsOptional, IsString } from "class-validator"
 import { Transform, Type } from "class-transformer"
-import {
-  IsArray,
-  IsNumber,
-  IsOptional,
-  IsString,
-} from "class-validator"
-import { pickBy } from "lodash"
+
 import BatchJobService from "../../../../services/batch-job"
 import { DateComparisonOperator } from "../../../../types/common"
 import { IsType } from "../../../../utils/validators/is-type"
 import { Request } from "express"
+import { pickBy } from "lodash"
 
 /**
  * @oas [get] /batch-jobs
@@ -18,20 +14,201 @@ import { Request } from "express"
  * description: "Retrieve a list of Batch Jobs."
  * x-authenticated: true
  * parameters:
- *   - (query) limit {string} The number of collections to return.
- *   - (query) offset {string} The offset of collections to return.
- *   - (query) type {string | string[]} Filter by the batch type
- *   - (query) confirmed_at {DateComparisonOperator | null} Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc.
- *   - (query) pre_processed_at {DateComparisonOperator | null} Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc.
- *   - (query) completed_at {DateComparisonOperator | null} Date comparison for when resulting collections was completed, i.e. less than, greater than etc.
- *   - (query) failed_at {DateComparisonOperator | null} Date comparison for when resulting collections was failed, i.e. less than, greater than etc.
- *   - (query) canceled_at {DateComparisonOperator | null} Date comparison for when resulting collections was canceled, i.e. less than, greater than etc.
- *   - (query) order {string} Order used when retrieving 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) deleted_at {DateComparisonOperator | null} Date comparison for when resulting collections was deleted, i.e. less than, greater than etc.
- *   - (query) created_at {DateComparisonOperator} Date comparison for when resulting collections was created, i.e. less than, greater than etc.
- *   - (query) updated_at {DateComparisonOperator} Date comparison for when resulting collections was updated, i.e. less than, greater than etc.
+ *   - (query) limit=10 {integer} The number of batch jobs to return.
+ *   - (query) offset=0 {integer} The number of batch jobs to skip before results.
+ *   - in: query
+ *     name: id
+ *     style: form
+ *     explode: false
+ *     description: Filter by the batch ID
+ *     schema:
+ *       oneOf:
+ *         - type: string
+ *           description: batch job ID
+ *         - type: array
+ *           description: multiple batch job IDs
+ *           items:
+ *             type: string
+ *   - in: query
+ *     name: type
+ *     style: form
+ *     explode: false
+ *     description: Filter by the batch type
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
+ *   - in: query
+ *     name: confirmed_at
+ *     style: form
+ *     explode: false
+ *     description: Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     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.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: completed_at
+ *     style: form
+ *     explode: false
+ *     description: Date comparison for when resulting collections was completed, i.e. less than, greater than etc.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: failed_at
+ *     style: form
+ *     explode: false
+ *     description: Date comparison for when resulting collections was failed, i.e. less than, greater than etc.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: canceled_at
+ *     style: form
+ *     explode: false
+ *     description: Date comparison for when resulting collections was canceled, i.e. less than, greater than etc.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            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.
+ *   - 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.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: updated_at
+ *     style: form
+ *     explode: false
+ *     description: Date comparison for when resulting collections was updated, i.e. less than, greater than etc.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
  * tags:
  *   - Batch Job
  * responses:
@@ -41,8 +218,19 @@ import { Request } from "express"
  *      application/json:
  *        schema:
  *          properties:
- *            batch_job:
- *              $ref: "#/components/schemas/batch_job"
+ *            batch_jobs:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/batch_job"
+ *            count:
+ *               type: integer
+ *               description: The total number of items available
+ *            offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *            limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req: Request, res) => {
   const batchService: BatchJobService = req.scope.resolve("batchJobService")

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

@@ -1,8 +1,9 @@
 import { ArrayNotEmpty, IsString } from "class-validator"
-import ProductCollectionService from "../../../../services/product-collection"
 import { Request, Response } from "express"
 import { EntityManager } from "typeorm";
 
+import ProductCollectionService from "../../../../services/product-collection"
+
 /**
  * @oas [post] /collections/{id}/products/batch
  * operationId: "PostProductsToCollection"
@@ -10,25 +11,31 @@ import { EntityManager } from "typeorm";
  * description: "Updates products associated with a Product Collection"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Collection.
+ *   - (path) id=* {string} The ID of the Collection.
  * requestBody:
  *   content:
  *     application/json:
  *       schema:
+ *         required:
+ *           - product_ids
  *         properties:
  *           product_ids:
  *             description: "An array of Product IDs to add to the Product Collection."
  *             type: array
  *             items:
- *               properties:
- *                 id:
- *                   description: "The ID of a Product to add to the Product Collection."
- *                   type: string
+ *               description: "The ID of a Product to add to the Product Collection."
+ *               type: string
  * tags:
  *   - Collection
  * responses:
  *  "200":
  *    description: OK
+ *    content:
+ *      application/json:
+ *        schema:
+ *          properties:
+ *            collection:
+ *              $ref: "#/components/schemas/product_collection"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

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

@@ -1,6 +1,7 @@
-import ProductCollectionService from "../../../../services/product-collection"
 import { Request, Response } from "express"
+
 import { EntityManager } from "typeorm";
+import ProductCollectionService from "../../../../services/product-collection"
 
 /**
  * @oas [delete] /collections/{id}
@@ -9,7 +10,7 @@ import { EntityManager } from "typeorm";
  * description: "Deletes a Product Collection."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Collection.
+ *   - (path) id=* {string} The ID of the Collection.
  * tags:
  *   - Collection
  * responses:
@@ -21,12 +22,15 @@ import { EntityManager } from "typeorm";
  *          properties:
  *            id:
  *              type: string
- *              description: The id of the deleted Collection
+ *              description: The ID of the deleted Collection
  *            object:
  *              type: string
  *              description: The type of the object that was deleted.
+ *              default: product-collection
  *            deleted:
  *              type: boolean
+ *              description: Whether the collection was deleted successfully or not.
+ *              default: true
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

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

@@ -1,6 +1,7 @@
-import { defaultAdminCollectionsRelations } from "."
-import ProductCollectionService from "../../../../services/product-collection"
 import { Request, Response } from "express"
+
+import ProductCollectionService from "../../../../services/product-collection"
+import { defaultAdminCollectionsRelations } from "."
 /**
  * @oas [get] /collections/{id}
  * operationId: "GetCollectionsCollection"
@@ -8,7 +9,7 @@ import { Request, Response } from "express"
  * description: "Retrieves a Product Collection."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Product Collection
+ *   - (path) id=* {string} The ID of the Product Collection
  * tags:
  *   - Collection
  * responses:

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

@@ -1,9 +1,10 @@
-import { Type } from "class-transformer"
 import { IsNumber, IsOptional, IsString, ValidateNested } from "class-validator"
-import _, { identity } from "lodash"
-import ProductCollectionService from "../../../../services/product-collection"
-import { DateComparisonOperator } from "../../../../types/common"
 import { Request, Response } from "express"
+import _, { identity } from "lodash"
+
+import { DateComparisonOperator } from "../../../../types/common"
+import ProductCollectionService from "../../../../services/product-collection"
+import { Type } from "class-transformer"
 
 /**
  * @oas [get] /collections
@@ -12,13 +13,77 @@ import { Request, Response } from "express"
  * description: "Retrieve a list of Product Collection."
  * x-authenticated: true
  * parameters:
- *   - (query) limit {string} The number of collections to return.
- *   - (query) offset {string} The offset of collections to return.
+ *   - (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) deleted_at {DateComparisonOperator} Date comparison for when resulting collections was deleted, i.e. less than, greater than etc.
- *   - (query) created_at {DateComparisonOperator} Date comparison for when resulting collections was created, i.e. less than, greater than etc.
- *   - (query) updated_at {DateComparisonOperator} Date comparison for when resulting collections was updated, i.e. less than, greater than etc.
+ *   - (query) q {string} a search term to search titles and handles.
+ *   - in: query
+ *     name: created_at
+ *     description: Date comparison for when resulting collections were created.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: updated_at
+ *     description: Date comparison for when resulting collections were updated.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: deleted_at
+ *     description: Date comparison for when resulting collections were deleted.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
  * tags:
  *   - Collection
  * responses:
@@ -28,8 +93,19 @@ import { Request, Response } from "express"
  *      application/json:
  *        schema:
  *          properties:
- *            collection:
- *              $ref: "#/components/schemas/product_collection"
+ *            collections:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/product_collection"
+ *            count:
+ *               type: integer
+ *               description: The total number of items available
+ *            offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *            limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req: Request, res: Response) => {
   const productCollectionService: ProductCollectionService = req.scope.resolve(

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

@@ -1,8 +1,9 @@
 import { ArrayNotEmpty, IsString } from "class-validator"
-import ProductCollectionService from "../../../../services/product-collection"
 import { Request, Response } from "express"
 import { EntityManager } from "typeorm";
 
+import ProductCollectionService from "../../../../services/product-collection"
+
 /**
  * @oas [delete] /collections/{id}/products/batch
  * operationId: "DeleteProductsFromCollection"
@@ -10,25 +11,42 @@ import { EntityManager } from "typeorm";
  * description: "Removes products associated with a Product Collection"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Collection.
+ *   - (path) id=* {string} The ID of the Collection.
  * requestBody:
  *   content:
  *     application/json:
  *       schema:
+ *         required:
+ *           - product_ids
  *         properties:
  *           product_ids:
  *             description: "An array of Product IDs to remove from the Product Collection."
  *             type: array
  *             items:
- *               properties:
- *                 id:
- *                   description: "The ID of a Product to remove from the Product Collection."
- *                   type: string
+ *               description: "The ID of a Product to add to the Product Collection."
+ *               type: string
  * tags:
  *   - Collection
  * responses:
  *  "200":
  *    description: OK
+ *    content:
+ *      application/json:
+ *        schema:
+ *          properties:
+ *            id:
+ *              type: string
+ *              description: "The ID of the collection"
+ *            object:
+ *              type: string
+ *              description: "The type of object the removal was executed on"
+ *              default: product-collection
+ *            removed_products:
+ *              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."
+ *                type: string
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

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

@@ -1,7 +1,9 @@
 import { IsObject, IsOptional, IsString } from "class-validator"
-import ProductCollectionService from "../../../../services/product-collection"
 import { Request, Response } from "express"
+
 import { EntityManager } from "typeorm";
+import ProductCollectionService from "../../../../services/product-collection"
+
 /**
  * @oas [post] /collections/{id}
  * operationId: "PostCollectionsCollection"
@@ -9,7 +11,7 @@ import { EntityManager } from "typeorm";
  * description: "Updates a Product Collection."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Collection.
+ *   - (path) id=* {string} The ID of the Collection.
  * requestBody:
  *   content:
  *     application/json:

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

@@ -1,10 +1,11 @@
-import { Type } from "class-transformer"
-import { ValidateNested } from "class-validator"
+import { Request, Response } from "express"
+
 import { CustomerGroupService } from "../../../../services"
 import { CustomerGroupsBatchCustomer } from "../../../../types/customer-groups"
-import { validator } from "../../../../utils/validator"
-import { Request, Response } from "express"
 import { EntityManager } from "typeorm"
+import { Type } from "class-transformer"
+import { ValidateNested } from "class-validator"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /customer-groups/{id}/customers/batch
@@ -13,10 +14,26 @@ import { EntityManager } from "typeorm"
  * description: "Adds a list of customers, represented by id's, to a customer group."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the customer group.
- *   - (body) customers=* {{id: string }[]} ids of the customers to add
+ *   - (path) id=* {string} The ID of the customer group.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - customer_ids
+ *         properties:
+ *           customer_ids:
+ *             description: "The ids of the customers to add"
+ *             type: array
+ *             items:
+ *               required:
+ *                 - id
+ *               properties:
+ *                 id:
+ *                   description: ID of the customer
+ *                   type: string
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK
@@ -24,8 +41,8 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             customerGroup:
- *               $ref: "#/components/schemas/customergroup"
+ *             customer_group:
+ *               $ref: "#/components/schemas/customer_group"
  */
 
 export default async (req: Request, res: Response) => {

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

@@ -1,8 +1,9 @@
 import { IsObject, IsOptional, IsString } from "class-validator"
-import { CustomerGroupService } from "../../../../services"
-import { validator } from "../../../../utils/validator"
 import { Request, Response } from "express"
+
+import { CustomerGroupService } from "../../../../services"
 import { EntityManager } from "typeorm"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /customer-groups
@@ -14,7 +15,7 @@ import { EntityManager } from "typeorm"
  *   - (body) name=* {string} Name of the customer group
  *   - (body) metadata {object} Metadata for the customer.
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK

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

@@ -1,5 +1,6 @@
-import { CustomerGroupService } from "../../../../services"
 import { Request, Response } from "express"
+
+import { CustomerGroupService } from "../../../../services"
 import { EntityManager } from "typeorm"
 
 /**
@@ -9,9 +10,9 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a CustomerGroup."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Customer Group
+ *   - (path) id=* {string} The ID of the Customer Group
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK
@@ -21,12 +22,15 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted customer group.
+ *               description: The ID of the deleted customer group.
  *             object:
  *               type: string
  *               description: The type of the object that was deleted.
+ *               default: customer_group
  *             deleted:
  *               type: boolean
+ *               description: Whether the customer group was deleted successfully or not.
+ *               default: true
  */
 
 export default async (req: Request, res: Response) => {

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

@@ -1,10 +1,11 @@
-import { Type } from "class-transformer"
-import { ValidateNested } from "class-validator"
+import { Request, Response } from "express"
+
 import { CustomerGroupService } from "../../../../services"
 import { CustomerGroupsBatchCustomer } from "../../../../types/customer-groups"
-import { validator } from "../../../../utils/validator"
-import { Request, Response } from "express"
 import { EntityManager } from "typeorm"
+import { Type } from "class-transformer"
+import { ValidateNested } from "class-validator"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [delete] /customer-groups/{id}/customers/batch
@@ -13,10 +14,26 @@ import { EntityManager } from "typeorm"
  * description: "Removes a list of customers, represented by id's, from a customer group."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the customer group.
- *   - (body) customers=* {{id: string }[]} ids of the customers to remove
+ *   - (path) id=* {string} The ID of the customer group.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - customer_ids
+ *         properties:
+ *           customer_ids:
+ *             description: "The ids of the customers to remove"
+ *             type: array
+ *             items:
+ *               required:
+ *                 - id
+ *               properties:
+ *                 id:
+ *                   description: ID of the customer
+ *                   type: string
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK
@@ -24,8 +41,8 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             customerGroup:
- *               $ref: "#/components/schemas/customergroup"
+ *             customer_group:
+ *               $ref: "#/components/schemas/customer_group"
  */
 
 export default async (req: Request, res: Response) => {

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

@@ -1,14 +1,17 @@
-import CustomerController from "../../../../controllers/customers"
 import { Request, Response } from "express"
 
+import CustomerController from "../../../../controllers/customers"
+
 /**
  * @oas [get] /customer-groups/{id}/customers
  * operationId: "GetCustomerGroupsGroupCustomers"
  * summary: "List Customers"
- * description: "Retrieves a list of Customers."
+ * description: "Retrieves a list of customers in a customer group"
  * x-authenticated: true
+ * parameters:
+ *   - (path) id=* {string} The ID of the customer group.
  * tags:
- *   - Customer
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK
@@ -16,8 +19,19 @@ import { Request, Response } from "express"
  *       application/json:
  *         schema:
  *           properties:
- *             customer:
- *               $ref: "#/components/schemas/customer"
+ *             customers:
+ *               type: array
+ *               items:
+ *                  $ref: "#/components/schemas/customer"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

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

@@ -1,6 +1,7 @@
+import { Request, Response } from "express"
+
 import { CustomerGroupService } from "../../../../services"
 import { FindParams } from "../../../../types/common"
-import { Request, Response } from "express"
 
 /**
  * @oas [get] /customer-groups/{id}
@@ -9,9 +10,11 @@ import { Request, Response } from "express"
  * description: "Retrieves a Customer Group."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Customer Group.
+ *   - (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.
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK

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

@@ -1,8 +1,9 @@
-import { Type } from "class-transformer"
 import { IsNumber, IsOptional, IsString } from "class-validator"
+import { Request, Response } from "express"
+
 import { CustomerGroupService } from "../../../../services"
 import { FilterableCustomerGroupProps } from "../../../../types/customer-groups"
-import { Request, Response } from "express"
+import { Type } from "class-transformer"
 
 /**
  * @oas [get] /customer-groups
@@ -11,18 +12,96 @@ import { Request, Response } from "express"
  * description: "Retrieve a list of customer groups."
  * x-authenticated: true
  * parameters:
- *   - (query) q {string} Query used for searching user group names.
- *   - (query) offset {string} How many groups to skip in the result.
- *   - (query) id {string} Ids of the groups to search for.
- *   - (query) order {string} to retrieve customer groups in.
- *   - (query) created_at {DateComparisonOperator} Date comparison for when resulting customer group was created, i.e. less than, greater than etc.
- *   - (query) updated_at {DateComparisonOperator} Date comparison for when resulting ustomer group was updated, i.e. less than, greater than etc.
- *   - (query) offset {string} How many customer groups to skip in the result.
- *   - (query) limit {string} Limit the number of customer groups returned.
+ *   - (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.
+ *   - in: query
+ *     name: id
+ *     style: form
+ *     explode: false
+ *     description: Filter by the customer group ID
+ *     schema:
+ *       oneOf:
+ *         - type: string
+ *           description: customer group ID
+ *         - type: array
+ *           description: multiple customer group IDs
+ *           items:
+ *             type: string
+ *         - type: object
+ *           properties:
+ *             lt:
+ *               type: string
+ *               description: filter by IDs less than this ID
+ *             gt:
+ *               type: string
+ *               description: filter by IDs greater than this ID
+ *             lte:
+ *               type: string
+ *               description: filter by IDs less than or equal to this ID
+ *             gte:
+ *               type: string
+ *               description: filter by IDs greater than or equal to this ID
+ *   - in: query
+ *     name: name
+ *     style: form
+ *     explode: false
+ *     description: Filter by the customer group name
+ *     schema:
+ *       type: array
+ *       description: multiple 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.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: updated_at
+ *     description: Date comparison for when resulting customer groups were updated.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            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.
 
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK
@@ -30,8 +109,19 @@ import { Request, Response } from "express"
  *       application/json:
  *         schema:
  *           properties:
- *             customerGroup:
- *               $ref: "#/components/schemas/customer_group"
+ *             customer_groups:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/customer_group"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req: Request, res: Response) => {
   const customerGroupService: CustomerGroupService = req.scope.resolve(

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

@@ -1,11 +1,11 @@
 import { IsObject, IsOptional, IsString } from "class-validator"
-import { defaultAdminCustomerGroupsRelations } from "."
+import { Request, Response } from "express"
 
 import { CustomerGroupService } from "../../../../services"
-import { FindParams } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
-import { Request, Response } from "express"
 import { EntityManager } from "typeorm"
+import { FindParams } from "../../../../types/common"
+import { defaultAdminCustomerGroupsRelations } from "."
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /customer-groups/{id}
@@ -14,11 +14,20 @@ import { EntityManager } from "typeorm"
  * description: "Update a CustomerGroup."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the customer group.
- *   - (body) name=* {string} Name of the customer group
- *   - (body) metadata {object} Metadata for the customer.
+ *   - (path) id=* {string} The ID of the customer group.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         properties:
+ *           name:
+ *             description: "Name of the customer group"
+ *             type: string
+ *           metadata:
+ *             description: "Metadata for the customer."
+ *             type: object
  * tags:
- *   - CustomerGroup
+ *   - Customer Group
  * responses:
  *   200:
  *     description: OK

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

@@ -1,4 +1,5 @@
 import { IsEmail, IsObject, IsOptional, IsString } from "class-validator"
+
 import { CustomerService } from "../../../../services"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
@@ -9,16 +10,40 @@ import { EntityManager } from "typeorm"
  * summary: "Create a Customer"
  * description: "Creates a Customer."
  * x-authenticated: true
- * parameters:
- *   - (body) email=* {string} The Customer's email address.
- *   - (body) first_name=* {string} The Customer's first name.
- *   - (body) last_name=* {string} The Customer's last name.
- *   - (body) phone {string} The Customer's phone number.
- *   - (body) metadata {object} Metadata for the customer.
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         required:
+ *           - email
+ *           - first_name
+ *           - last_name
+ *           - password
+ *         properties:
+ *           email:
+ *             type: string
+ *             description: The customer's email.
+ *             format: email
+ *           first_name:
+ *             type: string
+ *             description: The customer's first name.
+ *           last_name:
+ *             type: string
+ *             description: The customer's last name.
+ *           password:
+ *             type: string
+ *             description: The customer's password.
+ *             format: password
+ *           phone:
+ *             type: string
+ *             description: The customer's phone number.
+ *           metadata:
+ *             description: An optional set of key-value pairs to hold additional information.
+ *             type: object
  * tags:
  *   - Customer
  * responses:
- *   200:
+ *   201:
  *     description: OK
  *     content:
  *       application/json:

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

@@ -1,6 +1,6 @@
-import { defaultAdminCustomersRelations } from "."
 import CustomerService from "../../../../services/customer"
 import { FindParams } from "../../../../types/common"
+import { defaultAdminCustomersRelations } from "."
 import { validator } from "../../../../utils/validator"
 
 /**
@@ -10,7 +10,9 @@ import { validator } from "../../../../utils/validator"
  * description: "Retrieves a Customer."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Customer.
+ *   - (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.
  * tags:
  *   - Customer
  * responses:

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

@@ -1,13 +1,21 @@
-import { Type } from "class-transformer"
 import { IsNumber, IsOptional, IsString } from "class-validator"
-import customerController from "../../../../controllers/customers"
+
 import { AdminListCustomerSelector } from "../../../../types/customers"
+import { Type } from "class-transformer"
+import customerController from "../../../../controllers/customers"
+
 /**
  * @oas [get] /customers
  * operationId: "GetCustomers"
  * summary: "List Customers"
  * description: "Retrieves a list of Customers."
  * 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.
  * tags:
  *   - Customer
  * responses:
@@ -17,8 +25,19 @@ import { AdminListCustomerSelector } from "../../../../types/customers"
  *       application/json:
  *         schema:
  *           properties:
- *             customer:
- *               $ref: "#/components/schemas/customer"
+ *             customers:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/customer"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req, res) => {
   const result = await customerController.listAndCount(

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

@@ -6,13 +6,14 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
+
 import CustomerService from "../../../../services/customer"
-import { validator } from "../../../../utils/validator"
-import { defaultAdminCustomersRelations } from "."
-import { Type } from "class-transformer"
-import { FindParams } from "../../../../types/common"
 import { EntityManager } from "typeorm"
+import { FindParams } from "../../../../types/common"
+import { MedusaError } from "medusa-core-utils"
+import { Type } from "class-transformer"
+import { defaultAdminCustomersRelations } from "."
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /customers/{id}
@@ -21,7 +22,9 @@ import { EntityManager } from "typeorm"
  * description: "Updates a Customer."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Customer.
+ *   - (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.
  * requestBody:
  *   content:
  *     application/json:
@@ -29,7 +32,8 @@ import { EntityManager } from "typeorm"
  *         properties:
  *           email:
  *             type: string
- *             description: The Customer's email. Only providable if user not registered.
+ *             description: The Customer's email.
+ *             format: email
  *           first_name:
  *             type: string
  *             description:  The Customer's first name.
@@ -42,19 +46,20 @@ import { EntityManager } from "typeorm"
  *           password:
  *             type: string
  *             description: The Customer's password.
+ *             format: password
  *           groups:
  *             type: array
- *             description: A list of customer groups to which the customer belongs.
  *             items:
  *               required:
  *                 - id
  *               properties:
  *                 id:
- *                   description: The id of a customer group
+ *                   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
- *             description: Metadata for the customer.
  * tags:
  *   - Customer
  * responses:

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

@@ -1,7 +1,9 @@
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
 import { Discount } from "../../../.."
 import DiscountService from "../../../../services/discount"
 import { EntityManager } from "typeorm"
+
 /**
  * @oas [post] /discounts/{id}/regions/{region_id}
  * operationId: "PostDiscountsDiscountRegionsRegion"
@@ -9,8 +11,8 @@ import { EntityManager } from "typeorm"
  * description: "Adds a Region to the list of Regions that a Discount can be used in."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Discount.
- *   - (path) region_id=* {string} The id of the Region.
+ *   - (path) id=* {string} The ID of the Discount.
+ *   - (path) region_id=* {string} The ID of the Region.
  * tags:
  *   - Discount
  * responses:

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

@@ -1,19 +1,21 @@
+import { Discount, DiscountConditionOperator } from "../../../../models"
 import { IsOptional, IsString } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
-import { Discount, DiscountConditionOperator } from "../../../../models"
-import { DiscountService } from "../../../../services"
-import DiscountConditionService from "../../../../services/discount-condition"
+
 import { AdminUpsertConditionsReq } from "../../../../types/discount"
+import DiscountConditionService from "../../../../services/discount-condition"
+import { DiscountService } from "../../../../services"
+import { EntityManager } from "typeorm"
 import { getRetrieveConfig } from "../../../../utils/get-query-config"
 import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
+
 /**
  * @oas [post] /discounts/{discount_id}/conditions
  * operationId: "PostDiscountsDiscountConditions"
- * summary: "Creates a DiscountCondition"
+ * summary: "Creates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
  * x-authenticated: true
  * parameters:
- *   - (path) discount_id=* {string} The id of the Product.
+ *   - (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.
  * description: "Creates a DiscountCondition"
@@ -21,29 +23,41 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
+ *         required:
+ *           - operator
  *         properties:
  *           operator:
  *              description: Operator of the condition
  *              type: string
- *           items:
- *              properties:
- *                products:
- *                  type: array
- *                  description: list of products
- *                product_types:
- *                  type: array
- *                  description: list of product types
- *                product_collections:
- *                  type: array
- *                  description: list of product collections
- *                product_tags:
- *                  type: array
- *                  description: list of product tags
- *                customer_groups:
- *                  type: array
- *                  description: list of customer_groups
+ *              enum: [in, not_in]
+ *           products:
+ *              type: array
+ *              description: list of product IDs if the condition is applied on products.
+ *              items:
+ *                type: string
+ *           product_types:
+ *              type: array
+ *              description: list of product type IDs if the condition is applied on product types.
+ *              items:
+ *                type: string
+ *           product_collections:
+ *              type: array
+ *              description: list of product collection IDs if the condition is applied on product collections.
+ *              items:
+ *                type: string
+ *           product_tags:
+ *              type: array
+ *              description: list of product tag IDs if the condition is applied on product tags.
+ *              items:
+ *                type: string
+ *           customer_groups:
+ *              type: array
+ *              description: list of customer group IDs if the condition is applied on customer groups.
+ *              items:
+ *                type: string
+
  * tags:
- *   - Discount
+ *   - Discount Condition
  * responses:
  *   200:
  *     description: OK

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

@@ -1,4 +1,9 @@
-import { Type } from "class-transformer"
+import {
+  AllocationType,
+  Discount,
+  DiscountConditionOperator,
+  DiscountRuleType,
+} from "../../../../models"
 import {
   IsArray,
   IsBoolean,
@@ -13,47 +18,104 @@ import {
   ValidateNested,
 } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
-import {
-  AllocationType,
-  DiscountRuleType,
-  Discount,
-  DiscountConditionOperator,
-} from "../../../../models"
-import DiscountService from "../../../../services/discount"
+
+import { AdminPostDiscountsDiscountParams } from "./update-discount"
 import { AdminUpsertConditionsReq } from "../../../../types/discount"
-import { getRetrieveConfig } from "../../../../utils/get-query-config"
-import { validator } from "../../../../utils/validator"
+import DiscountService from "../../../../services/discount"
+import { EntityManager } from "typeorm"
 import { IsGreaterThan } from "../../../../utils/validators/greater-than"
 import { IsISO8601Duration } from "../../../../utils/validators/iso8601-duration"
-import { AdminPostDiscountsDiscountParams } from "./update-discount"
-import { EntityManager } from "typeorm"
+import { Type } from "class-transformer"
+import { getRetrieveConfig } from "../../../../utils/get-query-config"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /discounts
  * operationId: "PostDiscounts"
  * summary: "Creates a Discount"
  * x-authenticated: true
  * description: "Creates a Discount with a given set of rules that define how the Discount behaves."
+ * parameters:
+ *   - (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.
  * requestBody:
  *   content:
  *     application/json:
- *       required:
- *         - code
- *         - rule
  *       schema:
+ *         required:
+ *           - code
+ *           - rule
  *         properties:
  *           code:
  *             type: string
  *             description: A unique code that will be used to redeem the Discount
  *           is_dynamic:
- *             type: string
+ *             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.
+ *             default: false
  *           rule:
  *             description: The Discount Rule that defines how Discounts are calculated
- *             oneOf:
- *               - $ref: "#/components/schemas/discount_rule"
+ *             type: object
+ *             required:
+ *                - type
+ *                - value
+ *                - allocation
+ *             properties:
+ *               description:
+ *                 type: string
+ *                 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."
+ *                 enum: [fixed, percentage, free_shipping]
+ *               value:
+ *                 type: number
+ *                 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."
+ *                 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."
+ *                 items:
+ *                   type: object
+ *                   required:
+ *                      - operator
+ *                   properties:
+ *                     operator:
+ *                       type: string
+ *                       description: Operator of the condition
+ *                       enum: [in, not_in]
+ *                     products:
+ *                       type: array
+ *                       description: list of product IDs if the condition is applied on products.
+ *                       items:
+ *                         type: string
+ *                     product_types:
+ *                       type: array
+ *                       description: list of product type IDs if the condition is applied on product types.
+ *                       items:
+ *                         type: string
+ *                     product_collections:
+ *                       type: array
+ *                       description: list of product collection IDs if the condition is applied on product collections.
+ *                       items:
+ *                         type: string
+ *                     product_tags:
+ *                       type: array
+ *                       description: list of product tag IDs if the condition is applied on product tags.
+ *                       items:
+ *                         type: string
+ *                     customer_groups:
+ *                       type: array
+ *                       description: list of customer group IDs if the condition is applied on 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.
+ *             default: false
  *           starts_at:
  *             type: string
  *             format: date-time
@@ -62,6 +124,10 @@ import { EntityManager } from "typeorm"
  *             type: string
  *             format: date-time
  *             description: The time at which the Discount should no longer be available.
+ *           valid_duration:
+ *             type: string
+ *             description: Duration the discount runs between
+ *             example: P3Y6M4DT12H30M5S
  *           regions:
  *             description: A list of Region ids representing the Regions in which the Discount can be used.
  *             type: array

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

@@ -6,9 +6,11 @@ import {
   IsString,
 } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
 import DiscountService from "../../../../services/discount"
-import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /discounts/{id}/dynamic-codes
  * operationId: "PostDiscountsDiscountDynamicCodes"
@@ -16,9 +18,9 @@ import { EntityManager } from "typeorm"
  * description: "Creates a unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same behaviour."
  * 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 from."
  *   - (body) code=* {string} The unique code that will be used to redeem the Discount.
- *   - (body) usage_limit=* {number} amount of times the discount can be applied
+ *   - (body) usage_limit=1 {number} amount of times the discount can be applied.
  *   - (body) metadata {object} An optional set of key-value paris to hold additional information.
  * tags:
  *   - Discount

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

@@ -1,12 +1,13 @@
 import { IsOptional, IsString } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
 import { Discount } from "../../../../models"
-import { DiscountService } from "../../../../services"
 import DiscountConditionService from "../../../../services/discount-condition"
+import { DiscountService } from "../../../../services"
+import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
 import { getRetrieveConfig } from "../../../../utils/get-query-config"
 import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
 
 /**
  * @oas [delete] /discounts/{discount_id}/conditions/{condition_id}
@@ -15,10 +16,12 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a DiscountCondition"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Discount
- *   - (path) condition_id=* {string} The id of the DiscountCondition
+ *   - (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.
  * tags:
- *   - Discount
+ *   - Discount Condition
  * responses:
  *   200:
  *     description: OK
@@ -28,15 +31,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted DiscountCondition
+ *               description: The ID of the deleted DiscountCondition
  *             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.
+ *               default: true
  *             discount:
- *               type: object
  *               description: The Discount to which the condition used to belong
+ *               $ref: "#/components/schemas/discount"
  */
 export default async (req, res) => {
   const { discount_id, condition_id } = req.params

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a Discount."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Discount
+ *   - (path) id=* {string} The ID of the Discount
  * tags:
  *   - Discount
  * responses:
@@ -20,12 +20,15 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted Discount
+ *               description: The ID of the deleted Discount
  *             object:
  *               type: string
  *               description: The type of the object that was deleted.
+ *               default: discount
  *             deleted:
  *               type: boolean
+ *               description: Whether the discount was deleted successfully or not.
+ *               default: true
  */
 export default async (req, res) => {
   const { discount_id } = req.params

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

@@ -1,4 +1,5 @@
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
 import DiscountService from "../../../../services/discount"
 import { EntityManager } from "typeorm"
 
@@ -9,8 +10,8 @@ import { EntityManager } from "typeorm"
  * description: "Deletes 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) id=* {string} The ID of the Discount
+ *   - (path) code=* {string} The ID of the Discount
  * tags:
  *   - Discount
  * responses:

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

@@ -1,29 +1,30 @@
 import { IsOptional, IsString } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
 import {
   defaultAdminDiscountConditionFields,
   defaultAdminDiscountConditionRelations,
 } from "."
+
 import { DiscountCondition } from "../../../../models"
-import { DiscountService } from "../../../../services"
 import DiscountConditionService from "../../../../services/discount-condition"
+import { DiscountService } from "../../../../services"
+import { MedusaError } from "medusa-core-utils"
 import { getRetrieveConfig } from "../../../../utils/get-query-config"
 import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [get] /discounts/{discount_id}/conditions/{condition_id}
  * operationId: "GetDiscountsDiscountConditionsCondition"
  * summary: "Gets a DiscountCondition"
  * x-authenticated: true
  * parameters:
- *   - (path) discount_id=* {string} The id of the Discount.
- *   - (path) condition_id=* {string} The id of the DiscountCondition.
- * query:
- *  - (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) 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.
  * description: "Gets a DiscountCondition"
  
  * tags:
- *   - DiscountCondition
+ *   - Discount Condition
  * responses:
  *   200:
  *     description: OK

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

@@ -1,5 +1,6 @@
 import { IsOptional, IsString } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
 import { Discount } from "../../../../models"
 import DiscountService from "../../../../services/discount"
 import { getRetrieveConfig } from "../../../../utils/get-query-config"
@@ -12,6 +13,8 @@ import { validator } from "../../../../utils/validator"
  * 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.
  * tags:
  *   - Discount
  * responses:

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

@@ -1,5 +1,6 @@
 import { IsOptional, IsString } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
 import { Discount } from "../../../.."
 import DiscountService from "../../../../services/discount"
 import { getRetrieveConfig } from "../../../../utils/get-query-config"
@@ -11,10 +12,9 @@ import { validator } from "../../../../utils/validator"
  * description: "Retrieves a Discount"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Discount
- * query:
- *  - (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 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.
  * tags:
  *   - Discount
  * responses:

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

@@ -1,4 +1,3 @@
-import { Transform, Type } from "class-transformer"
 import {
   IsBoolean,
   IsInt,
@@ -6,13 +5,16 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
+import { Transform, Type } from "class-transformer"
 import _, { pickBy } from "lodash"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
+import { AdminGetDiscountsDiscountRuleParams } from "../../../../types/discount"
 import { Discount } from "../../../.."
 import DiscountService from "../../../../services/discount"
 import { FindConfig } from "../../../../types/common"
-import { AdminGetDiscountsDiscountRuleParams } from "../../../../types/discount"
 import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [get] /discounts
  * operationId: "GetDiscounts"
@@ -20,11 +22,25 @@ import { validator } from "../../../../utils/validator"
  * x-authenticated: true
  * description: "Retrieves a list of Discounts"
  * parameters:
- *   - (query) q {string} Search query applied on results.
+ *   - (query) q {string} Search query applied on the code field.
+ *   - in: query
+ *     name: rule
+ *     description: Discount Rules filters to apply on the search
+ *     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."
+ *         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 {number} The number of items in the response
- *   - (query) offset {number} The offset of items in response
+ *   - (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.
  * tags:
  *   - Discount
@@ -35,8 +51,19 @@ import { validator } from "../../../../utils/validator"
  *       application/json:
  *         schema:
  *           properties:
- *             discount:
- *               $ref: "#/components/schemas/discount"
+ *             discounts:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/discount"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req, res) => {
   const validated = await validator(AdminGetDiscountsParams, req.query)

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

@@ -1,6 +1,8 @@
-import DiscountService from "../../../../services/discount"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
+
+import DiscountService from "../../../../services/discount"
 import { EntityManager } from "typeorm"
+
 /**
  * @oas [delete] /discounts/{id}/regions/{region_id}
  * operationId: "DeleteDiscountsDiscountRegionsRegion"
@@ -8,8 +10,8 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * description: "Removes a Region from the list of Regions that a Discount can be used in."
  * parameters:
- *   - (path) id=* {string} The id of the Discount.
- *   - (path) region_id=* {string} The id of the Region.
+ *   - (path) id=* {string} The ID of the Discount.
+ *   - (path) region_id=* {string} The ID of the Region.
  * tags:
  *   - Discount
  * responses:

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

@@ -1,46 +1,55 @@
 import { IsOptional, IsString } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
-import { Discount } from "../../../../models"
-import { DiscountService } from "../../../../services"
-import DiscountConditionService from "../../../../services/discount-condition"
+
 import { AdminUpsertConditionsReq } from "../../../../types/discount"
+import { Discount } from "../../../../models"
+import DiscountConditionService from "../../../../services/discount-condition"
+import { DiscountService } from "../../../../services"
+import { EntityManager } from "typeorm"
 import { getRetrieveConfig } from "../../../../utils/get-query-config"
 import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
+
 /**
  * @oas [post] /discounts/{discount_id}/conditions/{condition_id}
  * operationId: "PostDiscountsDiscountConditionsCondition"
- * summary: "Updates a DiscountCondition"
+ * summary: "Updates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided."
  * 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 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.
  * description: "Updates a DiscountCondition"
  * requestBody:
  *   content:
  *     application/json:
- *       required:
- *         - id
  *       schema:
  *         properties:
- *           items:
- *              properties:
- *                products:
- *                  type: array
- *                  description: list of products
- *                product_types:
- *                  type: array
- *                  description: list of product types
- *                product_collections:
- *                  type: array
- *                  description: list of product collections
- *                product_tags:
- *                  type: array
- *                  description: list of product tags
- *                customer_groups:
- *                  type: array
- *                  description: list of customer_groups
+ *           products:
+ *              type: array
+ *              description: list of product IDs if the condition is applied on products.
+ *              items:
+ *                type: string
+ *           product_types:
+ *              type: array
+ *              description: list of product type IDs if the condition is applied on product types.
+ *              items:
+ *                type: string
+ *           product_collections:
+ *              type: array
+ *              description: list of product collection IDs if the condition is applied on product collections.
+ *              items:
+ *                type: string
+ *           product_tags:
+ *              type: array
+ *              description: list of product tag IDs if the condition is applied on product tags.
+ *              items:
+ *                type: string
+ *           customer_groups:
+ *              type: array
+ *              description: list of customer group IDs if the condition is applied on customer groups.
+ *              items:
+ *                type: string
  * tags:
  *   - Discount
  * responses:

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

@@ -1,4 +1,4 @@
-import { Type } from "class-transformer"
+import { Discount, DiscountConditionOperator } from "../../../../models"
 import {
   IsArray,
   IsBoolean,
@@ -13,15 +13,16 @@ import {
   ValidateNested,
 } from "class-validator"
 import { defaultAdminDiscountsFields, defaultAdminDiscountsRelations } from "."
-import { AllocationType } from "../../../../models"
-import { Discount, DiscountConditionOperator } from "../../../../models"
-import DiscountService from "../../../../services/discount"
+
 import { AdminUpsertConditionsReq } from "../../../../types/discount"
-import { getRetrieveConfig } from "../../../../utils/get-query-config"
-import { validator } from "../../../../utils/validator"
+import { AllocationType } from "../../../../models"
+import DiscountService from "../../../../services/discount"
+import { EntityManager } from "typeorm"
 import { IsGreaterThan } from "../../../../utils/validators/greater-than"
 import { IsISO8601Duration } from "../../../../utils/validators/iso8601-duration"
-import { EntityManager } from "typeorm"
+import { Type } from "class-transformer"
+import { getRetrieveConfig } from "../../../../utils/get-query-config"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /discounts/{id}
@@ -30,7 +31,9 @@ import { EntityManager } from "typeorm"
  * description: "Updates a Discount with a given set of rules that define how the Discount behaves."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Discount.
+ *   - (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.
  * requestBody:
  *   content:
  *     application/json:
@@ -41,23 +44,87 @@ import { EntityManager } from "typeorm"
  *             description: A unique code that will be used to redeem the Discount
  *           rule:
  *             description: The Discount Rule that defines how Discounts are calculated
- *             oneOf:
- *               - $ref: "#/components/schemas/discount_rule"
+ *             type: object
+ *             required:
+ *               - id
+ *             properties:
+ *               id:
+ *                 type: string
+ *                 description: "The ID of the Rule"
+ *               description:
+ *                 type: string
+ *                 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"
+ *               allocation:
+ *                 type: string
+ *                 description: "The scope that the discount should apply to."
+ *                 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."
+ *                 items:
+ *                   type: object
+ *                   required:
+ *                     - operator
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       description: "The ID of the Rule"
+ *                     operator:
+ *                       type: string
+ *                       description: Operator of the condition
+ *                       enum: [in, not_in]
+ *                     products:
+ *                       type: array
+ *                       description: list of product IDs if the condition is applied on products.
+ *                       items:
+ *                         type: string
+ *                     product_types:
+ *                       type: array
+ *                       description: list of product type IDs if the condition is applied on product types.
+ *                       items:
+ *                         type: string
+ *                     product_collections:
+ *                       type: array
+ *                       description: list of product collection IDs if the condition is applied on product collections.
+ *                       items:
+ *                         type: string
+ *                     product_tags:
+ *                       type: array
+ *                       description: list of product tag IDs if the condition is applied on product tags.
+ *                       items:
+ *                         type: string
+ *                     customer_groups:
+ *                       type: array
+ *                       description: list of customer group IDs if the condition is applied on 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.
  *           starts_at:
- *             type: Date
+ *             type: string
+ *             format: date-time
  *             description: The time at which the Discount should be available.
  *           ends_at:
- *             type: Date
+ *             type: string
+ *             format: date-time
  *             description: The time at which the Discount should no longer be available.
+ *           valid_duration:
+ *             type: string
+ *             description: Duration the discount runs between
+ *             example: P3Y6M4DT12H30M5S
+ *           usage_limit:
+ *             type: number
+ *             description: Maximum times the discount can be used
  *           regions:
  *             description: A list of Region ids representing the Regions in which the Discount can be used.
  *             type: array
  *             items:
  *               type: string
- *            metadata:
+ *           metadata:
  *              description: An object containing metadata of the discount
  *              type: object
  * tags:

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

@@ -1,4 +1,3 @@
-import { Type } from "class-transformer"
 import {
   IsArray,
   IsBoolean,
@@ -11,16 +10,19 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import { transformIdableFields } from "medusa-core-utils"
 import {
   defaultAdminDraftOrdersFields,
   defaultAdminDraftOrdersRelations,
 } from "."
+
+import { AddressPayload } from "../../../../types/common"
 import { DraftOrder } from "../../../.."
 import { DraftOrderService } from "../../../../services"
-import { AddressPayload } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
+import { Type } from "class-transformer"
+import { transformIdableFields } from "medusa-core-utils"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /draft-orders
  * operationId: "PostDraftOrders"
@@ -40,24 +42,27 @@ import { EntityManager } from "typeorm"
  *           status:
  *             description: "The status of the draft order"
  *             type: string
+ *             enum: [open, completed]
  *           email:
  *             description: "The email of the customer of the draft order"
  *             type: string
+ *             format: email
  *           billing_address:
  *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
  *           shipping_address:
  *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
  *           items:
  *             description: The Line Items that have been received.
  *             type: array
  *             items:
+ *               type: object
+ *               required:
+ *                 - quantity
  *               properties:
  *                 variant_id:
- *                   description: The id of the Product Variant to generate the Line Item from.
+ *                   description: The ID of the Product Variant to generate the Line Item from.
  *                   type: string
  *                 unit_price:
  *                   description: The potential custom price of the item.
@@ -72,18 +77,21 @@ import { EntityManager } from "typeorm"
  *                   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
+ *             description: The ID of the region for the draft order
  *             type: string
  *           discounts:
  *             description: The discounts to add on the draft order
  *             type: array
  *             items:
+ *               type: object
+ *               required:
+ *                 - code
  *               properties:
  *                 code:
  *                   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 to add on the draft order
  *             type: string
  *           no_notification_order:
  *             description: An optional flag passed to the resulting order to determine use of notifications.
@@ -92,9 +100,12 @@ import { EntityManager } from "typeorm"
  *             description: The shipping methods for the draft order
  *             type: array
  *             items:
+ *               type: object
+ *               required:
+ *                  - option_id
  *               properties:
  *                 option_id:
- *                   description: The id of the shipping option in use
+ *                   description: The ID of the shipping option in use
  *                   type: string
  *                 data:
  *                   description: The optional additional data needed for the shipping method

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

@@ -1,3 +1,8 @@
+import {
+  CartService,
+  DraftOrderService,
+  LineItemService,
+} from "../../../../services"
 import {
   IsBoolean,
   IsInt,
@@ -5,35 +10,34 @@ import {
   IsOptional,
   IsString,
 } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm"
 import {
   defaultAdminDraftOrdersCartFields,
   defaultAdminDraftOrdersCartRelations,
   defaultAdminDraftOrdersFields,
 } from "."
-import {
-  CartService,
-  DraftOrderService,
-  LineItemService,
-} from "../../../../services"
-import { validator } from "../../../../utils/validator"
+
+import { EntityManager } from "typeorm"
 import { FlagRouter } from "../../../../utils/flag-router"
+import { MedusaError } from "medusa-core-utils"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /draft-orders/{id}/line-items
  * operationId: "PostDraftOrdersDraftOrderLineItems"
  * summary: "Create a Line Item for Draft Order"
  * description: "Creates a Line Item for the Draft Order"
  * x-authenticated: true
+ * parameters:
+ *   - (path) id=* {string} The ID of the Draft Order.
  * requestBody:
  *   content:
  *     application/json:
- *       required:
- *         - quantity
  *       schema:
+ *         required:
+ *           - quantity
  *         properties:
  *           variant_id:
- *             description: The id of the Product Variant to generate the Line Item from.
+ *             description: The ID of the Product Variant to generate the Line Item from.
  *             type: string
  *           unit_price:
  *             description: The potential custom price of the item.
@@ -41,6 +45,7 @@ import { FlagRouter } from "../../../../utils/flag-router"
  *           title:
  *             description: The potential custom title of the item.
  *             type: string
+ *             default: "Custom item"
  *           quantity:
  *             description: The quantity of the Line Item.
  *             type: integer

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

@@ -7,7 +7,7 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a Draft Order"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
  * tags:
  *   - Draft Order
  * responses:
@@ -19,12 +19,15 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted Draft Order.
+ *               description: The ID of the deleted Draft Order.
  *             object:
  *               type: string
  *               description: The type of the object that was deleted.
+ *               default: draft-order
  *             deleted:
  *               type: boolean
+ *               description: Whether the draft order was deleted successfully or not.
+ *               default: true
  */
 export default async (req, res) => {
   const { id } = req.params

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

@@ -1,12 +1,14 @@
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm"
+import { CartService, DraftOrderService } from "../../../../services"
 import {
   defaultAdminDraftOrdersCartFields,
   defaultAdminDraftOrdersCartRelations,
   defaultAdminDraftOrdersFields,
 } from "."
+
 import { DraftOrder } from "../../../.."
-import { CartService, DraftOrderService } from "../../../../services"
+import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
+
 /**
  * @oas [delete] /draft-orders/{id}/line-items/{line_id}
  * operationId: DeleteDraftOrdersDraftOrderLineItemsItem
@@ -14,8 +16,8 @@ import { CartService, DraftOrderService } from "../../../../services"
  * description: "Removes 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) id=* {string} The ID of the Draft Order.
+ *   - (path) line_id=* {string} The ID of the Draft Order.
  * tags:
  *   - Draft Order
  * responses:

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

@@ -1,11 +1,12 @@
-import {
-  defaultAdminDraftOrdersRelations,
-  defaultAdminDraftOrdersFields,
-  defaultAdminDraftOrdersCartRelations,
-  defaultAdminDraftOrdersCartFields,
-} from "."
-import { DraftOrder } from "../../../.."
 import { CartService, DraftOrderService } from "../../../../services"
+import {
+  defaultAdminDraftOrdersCartFields,
+  defaultAdminDraftOrdersCartRelations,
+  defaultAdminDraftOrdersFields,
+  defaultAdminDraftOrdersRelations,
+} from "."
+
+import { DraftOrder } from "../../../.."
 
 /**
  * @oas [get] /draft-orders/{id}
@@ -14,7 +15,7 @@ import { CartService, DraftOrderService } from "../../../../services"
  * description: "Retrieves a Draft Order."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
  * tags:
  *   - Draft Order
  * responses:

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

@@ -1,20 +1,26 @@
+import { IsNumber, IsOptional, IsString } from "class-validator"
 import {
   defaultAdminDraftOrdersFields,
   defaultAdminDraftOrdersRelations,
 } from "."
-import { DraftOrderService } from "../../../../services"
-import { IsNumber, IsOptional, IsString } from "class-validator"
-import { validator } from "../../../../utils/validator"
-import { Type } from "class-transformer"
-import { DraftOrderListSelector } from "../../../../types/draft-orders"
-import { FindConfig } from "../../../../types/common"
+
 import { DraftOrder } from "../../../../models"
+import { DraftOrderListSelector } from "../../../../types/draft-orders"
+import { DraftOrderService } from "../../../../services"
+import { FindConfig } from "../../../../types/common"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [get] /draft-orders
  * operationId: "GetDraftOrders"
  * summary: "List Draft Orders"
  * description: "Retrieves an list of Draft Orders"
  * 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
  * tags:
  *   - Draft Order
  * responses:
@@ -24,8 +30,19 @@ import { DraftOrder } from "../../../../models"
  *       application/json:
  *         schema:
  *           properties:
- *             draft_order:
- *               $ref: "#/components/schemas/draft-order"
+ *             draft_orders:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/draft-order"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 
 export default async (req, res) => {

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

@@ -1,4 +1,3 @@
-import { EntityManager } from "typeorm"
 import {
   CartService,
   DraftOrderService,
@@ -10,8 +9,10 @@ import {
   defaultAdminOrdersRelations as defaultOrderRelations,
 } from "../orders/index"
 
+import { EntityManager } from "typeorm"
+
 /**
- * @oas [post] /draft-orders/{id}/register-payment
+ * @oas [post] /draft-orders/{id}/pay
  * summary: "Registers a payment for a Draft Order"
  * operationId: "PostDraftOrdersDraftOrderRegisterPayment"
  * description: "Registers a payment for a Draft Order."
@@ -27,7 +28,7 @@ import {
  *       application/json:
  *         schema:
  *           properties:
- *             draft_order:
+ *             order:
  *               $ref: "#/components/schemas/draft-order"
  */
 

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

@@ -1,8 +1,4 @@
-import { MedusaError } from "medusa-core-utils"
-import {
-  defaultAdminDraftOrdersCartFields,
-  defaultAdminDraftOrdersCartRelations,
-} from "."
+import { CartService, DraftOrderService } from "../../../../services"
 import {
   IsArray,
   IsBoolean,
@@ -11,12 +7,17 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import { CartService, DraftOrderService } from "../../../../services"
-import { Type } from "class-transformer"
+import {
+  defaultAdminDraftOrdersCartFields,
+  defaultAdminDraftOrdersCartRelations,
+} from "."
+
 import { AddressPayload } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
 import { DraftOrderStatus } from "../../../../models"
+import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /admin/draft-orders/{id}
@@ -25,7 +26,7 @@ import { DraftOrderStatus } from "../../../../models"
  * description: "Updates a Draft Order."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -33,22 +34,30 @@ import { DraftOrderStatus } from "../../../../models"
  *         properties:
  *           region_id:
  *             type: string
- *             description: The id of the Region to create the Draft Order in.
+ *             description: The ID of the Region to create the Draft Order in.
+ *           country_code:
+ *             type: string
+ *             description: "The 2 character ISO code for the Country."
+ *             externalDocs:
+ *                url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *                description: See a list of codes.
  *           email:
  *             type: string
  *             description: "An email to be used on the Draft Order."
+ *             format: email
  *           billing_address:
  *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
  *           shipping_address:
  *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
  *           discounts:
  *             description: "An array of Discount codes to add to the Draft Order."
  *             type: array
  *             items:
+ *               type: object
+ *               required:
+ *                 - code
  *               properties:
  *                 code:
  *                   description: "The code that a Discount is identifed by."
@@ -57,7 +66,7 @@ import { DraftOrderStatus } from "../../../../models"
  *             description: "An optional flag passed to the resulting order to determine use of notifications."
  *             type: boolean
  *           customer_id:
- *             description: "The id of the Customer to associate the Draft Order with."
+ *             description: "The ID of the Customer to associate the Draft Order with."
  *             type: string
  * tags:
  *   - Draft Order

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

@@ -1,21 +1,26 @@
+import { CartService, DraftOrderService } from "../../../../services"
 import { IsInt, IsObject, IsOptional, IsString } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm"
 import {
   defaultAdminDraftOrdersCartFields,
   defaultAdminDraftOrdersCartRelations,
   defaultAdminDraftOrdersFields,
 } from "."
+
 import { DraftOrder } from "../../../.."
+import { EntityManager } from "typeorm"
 import { LineItemUpdate } from "../../../../types/cart"
-import { CartService, DraftOrderService } from "../../../../services"
+import { MedusaError } from "medusa-core-utils"
 import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /draft-orders/{id}/line-items/{line_id}
  * operationId: "PostDraftOrdersDraftOrderLineItemsItem"
  * summary: "Update a Line Item for a Draft Order"
  * description: "Updates a Line Item for a Draft Order"
  * x-authenticated: true
+ * parameters:
+ *   - (path) id=* {string} The ID of the Draft Order.
+ *   - (path) line_id=* {string} The ID of the Line Item.
  * requestBody:
  *   content:
  *     application/json:

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

@@ -1,7 +1,8 @@
-import { Type } from "class-transformer"
 import { IsBoolean, IsDate, IsInt, IsOptional, IsString } from "class-validator"
 import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "."
+
 import { GiftCardService } from "../../../../services"
+import { Type } from "class-transformer"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -15,6 +16,8 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
+ *         required:
+ *           - region_id
  *         properties:
  *           value:
  *             type: integer
@@ -27,10 +30,8 @@ import { EntityManager } from "typeorm"
  *             format: date-time
  *             description: The 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: array
- *             items:
- *               type: string
+ *             description: The ID of the Region in which the Gift Card can be used.
+ *             type: string
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object

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

@@ -7,7 +7,7 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a Gift Card"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Gift Card to delete.
+ *   - (path) id=* {string} The ID of the Gift Card to delete.
  * tags:
  *   - Gift Card
  * responses:
@@ -19,12 +19,15 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted Gift Card
+ *               description: The ID of the deleted Gift Card
  *             object:
  *               type: string
  *               description: The type of the object that was deleted.
+ *               default: gift-card
  *             deleted:
  *               type: boolean
+ *               description: Whether the gift card was deleted successfully or not.
+ *               default: true
  */
 export default async (req, res) => {
   const { id } = req.params

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

@@ -7,7 +7,7 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  * description: "Retrieves a Gift Card."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Gift Card.
+ *   - (path) id=* {string} The ID of the Gift Card.
  * tags:
  *   - Gift Card
  * responses:

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

@@ -1,7 +1,8 @@
-import { Type } from "class-transformer"
 import { IsInt, IsOptional, IsString } from "class-validator"
-import { pickBy } from "lodash"
+
 import { GiftCardService } from "../../../../services"
+import { Type } from "class-transformer"
+import { pickBy } from "lodash"
 import { validator } from "../../../../utils/validator"
 
 /**
@@ -10,6 +11,10 @@ import { validator } from "../../../../utils/validator"
  * summary: "List Gift Cards"
  * description: "Retrieves a list of Gift Cards."
  * 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
  * tags:
  *   - Gift Card
  * responses:
@@ -23,6 +28,15 @@ import { validator } from "../../../../utils/validator"
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/gift_card"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req, res) => {
   const validated = await validator(AdminGetGiftCardsParams, req.query)

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

@@ -1,7 +1,8 @@
-import { Type } from "class-transformer"
 import { IsBoolean, IsDate, IsInt, IsOptional, IsString } from "class-validator"
 import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "."
+
 import { GiftCardService } from "../../../../services"
+import { Type } from "class-transformer"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -12,7 +13,7 @@ import { EntityManager } from "typeorm"
  * description: "Creates a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Gift Card.
+ *   - (path) id=* {string} The ID of the Gift Card.
  * requestBody:
  *   content:
  *     application/json:
@@ -29,10 +30,8 @@ import { EntityManager } from "typeorm"
  *             format: date-time
  *             description: The 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: array
- *             items:
- *               type: string
+ *             description: The ID of the Region in which the Gift Card can be used.
+ *             type: string
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object

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

@@ -1,6 +1,7 @@
-import { Type } from "class-transformer"
 import { IsNotEmpty, IsString, ValidateNested } from "class-validator"
+
 import InviteService from "../../../../services/invite"
+import { Type } from "class-transformer"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -37,8 +38,9 @@ import { EntityManager } from "typeorm"
  *               password:
  *                 description: The desired password for the User
  *                 type: string
+ *                 format: password
  * tags:
- *   - Invites
+ *   - Invite
  * responses:
  *   200:
  *     description: OK

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

@@ -1,6 +1,7 @@
 import { IsEmail, IsEnum } from "class-validator"
-import { UserRoles } from "../../../../models/user"
+
 import InviteService from "../../../../services/invite"
+import { UserRoles } from "../../../../models/user"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -21,11 +22,13 @@ import { EntityManager } from "typeorm"
  *           user:
  *             description: "The email for the user to be created."
  *             type: string
+ *             format: email
  *           role:
  *             description: "The role of the user to be created."
  *             type: string
+ *             enum: [admin, member, developer]
  * tags:
- *   - Invites
+ *   - Invite
  * responses:
  *   200:
  *     description: OK

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

@@ -1,5 +1,5 @@
-import InviteService from "../../../../services/invite"
 import { EntityManager } from "typeorm"
+import InviteService from "../../../../services/invite"
 
 /**
  * @oas [delete] /invites/{invite_id}
@@ -8,12 +8,27 @@ import { EntityManager } from "typeorm"
  * description: "Creates an Invite and triggers an 'invite' created event"
  * x-authenticated: true
  * parameters:
- *   - (path) invite_id=* {string} The id of the Invite
+ *   - (path) invite_id=* {string} The ID of the Invite
  * tags:
- *   - Invites
+ *   - Invite
  * responses:
  *   200:
  *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           properties:
+ *             id:
+ *               type: string
+ *               description: The ID of the deleted Invite.
+ *             object:
+ *               type: string
+ *               description: The type of the object that was deleted.
+ *               format: invite
+ *             deleted:
+ *               type: boolean
+ *               description: Whether or not the Invite was deleted.
+ *               default: true
  */
 export default async (req, res) => {
   const { invite_id } = req.params

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

@@ -7,7 +7,7 @@ import InviteService from "../../../../services/invite"
  * description: "Lists all Invites"
  * x-authenticated: true
  * tags:
- *   - Invites
+ *   - Invite
  * responses:
  *   200:
  *     description: OK

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

@@ -8,9 +8,9 @@ import { EntityManager } from "typeorm"
  * description: "Resends an Invite by triggering the 'invite' created event again"
  * x-authenticated: true
  * parameters:
- *   - (path) invite_id=* {string} The id of the Invite
+ *   - (path) invite_id=* {string} The ID of the Invite
  * tags:
- *   - Invites
+ *   - Invite
  * responses:
  *   200:
  *     description: OK

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

@@ -1,4 +1,5 @@
 import { IsNotEmpty, IsString } from "class-validator"
+
 import NoteService from "../../../../services/note"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
@@ -13,10 +14,14 @@ import { EntityManager } from "typeorm"
  *  content:
  *    application/json:
  *      schema:
+ *        required:
+ *          - resource_id
+ *          - resource_type
+ *          - value
  *        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.
  *          resource_type:
  *            type: string
  *            description: The type of resource which the Note relates to.

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

@@ -1,5 +1,5 @@
-import NoteService from "../../../../services/note"
 import { EntityManager } from "typeorm"
+import NoteService from "../../../../services/note"
 
 /**
  * @oas [delete] /notes/{id}
@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a Note."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Note to delete.
+ *   - (path) id=* {string} The ID of the Note to delete.
  * tags:
  *   - Note
  * responses:
@@ -20,10 +20,15 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted Note.
+ *               description: The ID of the deleted Note.
+ *             object:
+ *               type: string
+ *               description: The type of the object that was deleted.
+ *               default: note
  *             deleted:
  *               type: boolean
  *               description: Whether or not the Note was deleted.
+ *               default: true
  */
 export default async (req, res) => {
   const { id } = req.params

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

@@ -7,7 +7,7 @@ import NoteService from "../../../../services/note"
  * description: "Retrieves a single note using its id"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the note to retrieve.
+ *   - (path) id=* {string} The ID of the note to retrieve.
  * tags:
  *   - Note
  * responses:

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

@@ -1,18 +1,20 @@
 import { IsNumber, IsOptional, IsString } from "class-validator"
+
 import NoteService from "../../../../services/note"
-import { validator } from "../../../../utils/validator"
-import { selector } from "../../../../types/note"
 import { Type } from "class-transformer"
+import { selector } from "../../../../types/note"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [get] /notes
  * operationId: "GetNotes"
  * summary: "List Notes"
  * x-authenticated: true
  * description: "Retrieves a list of notes"
- *  * parameters:
- *   - (path) limit= {number} The number of notes to get
- *   - (path) offset= {number} The offset at which to get notes
- *   - (path) resource_id= {string} The id which the notes belongs to
+ * 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
  * tags:
  *   - Note
  * responses:
@@ -26,6 +28,15 @@ import { Type } from "class-transformer"
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/note"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req, res) => {
   const validated = await validator(AdminGetNotesParams, req.query)

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

@@ -10,7 +10,7 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * description: "Updates a Note associated with some resource"
  * parameters:
- *   - (path) id=* {string} The id of the Note to update
+ *   - (path) id=* {string} The ID of the Note to update
  * requestBody:
  *  content:
  *    application/json:

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

@@ -1,8 +1,4 @@
-import { Type } from "class-transformer"
 import { IsBooleanString, IsInt, IsOptional, IsString } from "class-validator"
-import { pick } from "lodash"
-import { NotificationService } from "../../../../services"
-import { validator } from "../../../../utils/validator"
 import {
   defaultAdminNotificationsFields,
   defaultAdminNotificationsRelations,
@@ -10,6 +6,11 @@ import {
 import { Notification } from "../../../../models"
 import { FindConfig } from "../../../../types/common"
 
+import { NotificationService } from "../../../../services"
+import { Type } from "class-transformer"
+import { pick } from "lodash"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [get] /notifications
  * operationId: "GetNotifications"
@@ -19,13 +20,13 @@ import { FindConfig } from "../../../../types/common"
  * 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} The fields to include in the result set
- *   - (query) expand {string} The fields to populate
- *   - (query) event_name {string}
- *   - (query) resource_type {string}
- *   - (query) resource_id {string}
- *   - (query) to {string}
- *   - (query) include_resends {boolean} Whether the result set should include resent notifications or not
+ *   - (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) include_resends {string} A boolean indicating whether the result set should include resent notifications or not
  * tags:
  *   - Notification
  * responses:

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

@@ -1,13 +1,14 @@
-import { IsString } from "class-validator"
-import { IsOptional } from "class-validator"
 import {
   defaultAdminNotificationsFields,
   defaultAdminNotificationsRelations,
 } from "."
-import { validator } from "../../../../utils/validator"
-import { NotificationService } from "../../../../services"
-import { Notification } from "../../../../models"
+
 import { EntityManager } from "typeorm"
+import { IsOptional } from "class-validator"
+import { IsString } from "class-validator"
+import { Notification } from "../../../../models"
+import { NotificationService } from "../../../../services"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /notifications/{id}/resend
@@ -16,14 +17,14 @@ import { EntityManager } from "typeorm"
  * description: "Resends 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
+ *   - (path) id=* {string} The ID of the Notification
  * requestBody:
  *   content:
  *     application/json:
  *       schema:
  *         properties:
  *           to:
- *             description: "The address or user identifier that the Notification was sent to"
+ *             description: "A new address or user identifier that the Notification should be sent to"
  *             type: string
  * tags:
  *   - Notification

packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts

@@ -6,6 +6,7 @@ import {
   IsString,
 } from "class-validator"
 import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { OrderService } from "../../../../services"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
@@ -17,10 +18,10 @@ import { EntityManager } from "typeorm"
  * description: "Adds a Shipping Method to an Order. If another Shipping Method exists with the same Shipping Profile, the previous Shipping Method will be replaced."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  *   - (body) price=* {integer} The price (excluding VAT) that should be charged for the Shipping Method
- *   - (body) option_id=* {string} The id of the Shipping Option to create the Shipping Method from.
- *   - (body) data=* {object} The data required for the Shipping Option to create a Shipping Method. This will depend on the Fulfillment Provider.
+ *   - (body) option_id=* {string} The ID of the Shipping Option to create the Shipping Method from.
+ *   - (body) data {object} The data required for the Shipping Option to create a Shipping Method. This will depend on the Fulfillment Provider.
  * tags:
  *   - Order
  * responses:

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Archives the order with the given id."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * tags:
  *   - Order
  * responses:

packages/medusa/src/api/routes/admin/orders/cancel-claim.ts

@@ -1,7 +1,8 @@
-import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import { ClaimService, OrderService } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
 
 /**
  * @oas [post] /orders/{id}/claims/{claim_id}/cancel
@@ -10,8 +11,8 @@ import { EntityManager } from "typeorm"
  * description: "Cancels a Claim"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) claim_id=* {string} The id of the Claim.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) claim_id=* {string} The ID of the Claim.
  * tags:
  *   - Claim
  * responses:
@@ -22,7 +23,7 @@ import { EntityManager } from "typeorm"
  *         schema:
  *           properties:
  *             order:
- *               $ref: "#/components/schemas/claim_order"
+ *               $ref: "#/components/schemas/order"
  */
 export default async (req, res) => {
   const { id, claim_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts

@@ -1,11 +1,12 @@
-import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import {
   ClaimService,
   FulfillmentService,
   OrderService,
 } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
 
 /**
  * @oas [post] /orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel
@@ -14,9 +15,9 @@ import { EntityManager } from "typeorm"
  * description: "Registers a Fulfillment as canceled."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order which the Claim relates to.
- *   - (path) claim_id=* {string} The id of the Claim which the Fulfillment relates to.
- *   - (path) fulfillment_id=* {string} The id of the Fulfillment.
+ *   - (path) id=* {string} The ID of the Order which the Claim relates to.
+ *   - (path) claim_id=* {string} The ID of the Claim which the Fulfillment relates to.
+ *   - (path) fulfillment_id=* {string} The ID of the Fulfillment.
  * tags:
  *   - Fulfillment
  * responses:
@@ -26,8 +27,8 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             fulfillment:
- *               $ref: "#/components/schemas/fulfillment"
+ *             order:
+ *               $ref: "#/components/schemas/order"
  */
 export default async (req, res) => {
   const { id, claim_id, fulfillment_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts

@@ -1,11 +1,12 @@
-import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import {
   FulfillmentService,
   OrderService,
   SwapService,
 } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
 
 /**
  * @oas [post] /orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel
@@ -14,9 +15,9 @@ import { EntityManager } from "typeorm"
  * description: "Registers a Fulfillment as canceled."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order which the Swap relates to.
- *   - (path) swap_id=* {string} The id of the Swap which the Fulfillment relates to.
- *   - (path) fulfillment_id=* {string} The id of the Fulfillment.
+ *   - (path) id=* {string} The ID of the Order which the Swap relates to.
+ *   - (path) swap_id=* {string} The ID of the Swap which the Fulfillment relates to.
+ *   - (path) fulfillment_id=* {string} The ID of the Fulfillment.
  * tags:
  *   - Fulfillment
  * responses:
@@ -26,8 +27,8 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             fulfillment:
- *               $ref: "#/components/schemas/fulfillment"
+ *             order:
+ *               $ref: "#/components/schemas/order"
  */
 export default async (req, res) => {
   const { id, swap_id, fulfillment_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts

@@ -1,7 +1,8 @@
-import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import { FulfillmentService, OrderService } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
 
 /**
  * @oas [post] /orders/{id}/fulfillments/{fulfillment_id}/cancel
@@ -10,8 +11,8 @@ import { EntityManager } from "typeorm"
  * description: "Registers a Fulfillment as canceled."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order which the Fulfillment relates to.
- *   - (path) fulfillment_id=* {string} The id of the Fulfillment
+ *   - (path) id=* {string} The ID of the Order which the Fulfillment relates to.
+ *   - (path) fulfillment_id=* {string} The ID of the Fulfillment
  * tags:
  *   - Fulfillment
  * responses:
@@ -21,8 +22,8 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             fulfillment:
- *               $ref: "#/components/schemas/fulfillment"
+ *             order:
+ *               $ref: "#/components/schemas/order"
  */
 export default async (req, res) => {
   const { id, fulfillment_id } = req.params

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

@@ -1,4 +1,5 @@
 import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { OrderService } from "../../../../services"
 import { EntityManager } from "typeorm"
 
@@ -9,7 +10,7 @@ import { EntityManager } from "typeorm"
  * description: "Registers an Order as canceled. This triggers a flow that will cancel any created Fulfillments and Payments, may fail if the Payment or Fulfillment Provider is unable to cancel the Payment/Fulfillment."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * tags:
  *   - Order
  * responses:

packages/medusa/src/api/routes/admin/orders/cancel-swap.ts

@@ -1,7 +1,8 @@
-import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import { OrderService, SwapService } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
 
 /**
  * @oas [post] /orders/{id}/swaps/{swap_id}/cancel
@@ -10,8 +11,8 @@ import { EntityManager } from "typeorm"
  * description: "Cancels a Swap"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) swap_id=* {string} The id of the Swap.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) swap_id=* {string} The ID of the Swap.
  * tags:
  *   - Swap
  * responses:
@@ -22,7 +23,7 @@ import { EntityManager } from "typeorm"
  *         schema:
  *           properties:
  *             order:
- *               $ref: "#/components/schemas/swap"
+ *               $ref: "#/components/schemas/order"
  */
 export default async (req, res) => {
   const { id, swap_id } = req.params

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

@@ -1,4 +1,5 @@
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { OrderService } from "../../../../services"
 import { EntityManager } from "typeorm"
 
@@ -9,7 +10,7 @@ import { EntityManager } from "typeorm"
  * description: "Captures all the Payments associated with an Order."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * tags:
  *   - Order
  * responses:

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Completes an Order"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * tags:
  *   - Order
  * responses:

packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts

@@ -1,6 +1,7 @@
+import { ClaimService, OrderService } from "../../../../services"
 import { IsArray, IsNotEmpty, IsOptional, IsString } from "class-validator"
 import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
-import { ClaimService, OrderService } from "../../../../services"
+
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -11,8 +12,8 @@ import { EntityManager } from "typeorm"
  * description: "Registers a Claim Fulfillment as shipped."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) claim_id=* {string} The id of the Claim.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) claim_id=* {string} The ID of the Claim.
  * requestBody:
  *   content:
  *     application/json:
@@ -21,7 +22,7 @@ import { EntityManager } from "typeorm"
  *           - fulfillment_id
  *         properties:
  *           fulfillment_id:
- *             description: The id of the Fulfillment.
+ *             description: The ID of the Fulfillment.
  *             type: string
  *           tracking_numbers:
  *             description: The tracking numbers for the shipment.
@@ -29,7 +30,7 @@ import { EntityManager } from "typeorm"
  *             items:
  *               type: string
  * tags:
- *   - Order
+ *   - Claim
  * responses:
  *   200:
  *     description: OK

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

@@ -1,4 +1,4 @@
-import { Type } from "class-transformer"
+import { ClaimReason, ClaimType } from "../../../../models"
 import {
   IsArray,
   IsBoolean,
@@ -10,13 +10,14 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
 import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { AddressPayload } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
 import { ClaimTypeValue } from "../../../../types/claim"
-import { ClaimType, ClaimReason } from "../../../../models"
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /order/{id}/claims
@@ -25,7 +26,7 @@ import { EntityManager } from "typeorm"
  * description: "Creates a Claim."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -44,9 +45,12 @@ import { EntityManager } from "typeorm"
  *             description: The Claim Items that the Claim will consist of.
  *             type: array
  *             items:
+ *               required:
+ *                 - item_id
+ *                 - quantity
  *               properties:
  *                 item_id:
- *                   description: The id of the Line Item that will be claimed.
+ *                   description: The ID of the Line Item that will be claimed.
  *                   type: string
  *                 quantity:
  *                   description: The number of items that will be returned
@@ -71,55 +75,59 @@ import { EntityManager } from "typeorm"
  *                   description: A list of image URL's that will be associated with the Claim
  *                   items:
  *                     type: string
- *            return_shipping:
+ *           return_shipping:
  *              description: Optional details for the Return Shipping Method, if the items are to be sent back.
  *              type: object
  *              properties:
  *                option_id:
  *                  type: string
- *                  description: The id of the Shipping Option to create the Shipping Method from.
+ *                  description: The ID of the Shipping Option to create the Shipping Method from.
  *                price:
  *                  type: integer
  *                  description: The price to charge for the Shipping Method.
- *            additional_items:
+ *           additional_items:
  *              description: The new items to send to the Customer when the Claim type is Replace.
  *              type: array
  *              items:
+ *                required:
+ *                  - variant_id
+ *                  - quantity
  *                properties:
  *                  variant_id:
- *                    description: The id of the Product Variant to ship.
+ *                    description: The ID of the Product Variant to ship.
  *                    type: string
  *                  quantity:
  *                    description: The quantity of the Product Variant to ship.
  *                    type: integer
- *            shipping_methods:
+ *           shipping_methods:
  *              description: The Shipping Methods to send the additional Line Items with.
  *              type: array
  *              items:
  *                 properties:
  *                   id:
- *                     description: The id of an existing Shipping Method
+ *                     description: The ID of an existing Shipping Method
  *                     type: string
  *                   option_id:
- *                     description: The id of the Shipping Option to create a Shipping Method from
+ *                     description: The ID of the Shipping Option to create a Shipping Method from
  *                     type: string
  *                   price:
  *                     description: The price to charge for the Shipping Method
  *                     type: integer
- *            shipping_address:
+ *           shipping_address:
  *              type: object
  *              description: "An optional shipping address to send the claim to. Defaults to the parent order's shipping address"
- *            refund_amount:
+ *              $ref: "#/components/schemas/address"
+ *           refund_amount:
  *              description: The amount to refund the Customer when the Claim type is `refund`.
  *              type: integer
- *            no_notification:
+ *           no_notification:
  *              description: If set to true no notification will be send related to this Claim.
  *              type: boolean
- *            metadata:
+ *           metadata:
  *              description: An optional set of key-value pairs to hold additional information.
  *              type: object
  * tags:
- *   - Order
+ *   - Claim
  * responses:
  *   200:
  *     description: OK

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

@@ -1,4 +1,3 @@
-import { Transform, Type } from "class-transformer"
 import {
   IsArray,
   IsBoolean,
@@ -9,18 +8,21 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
+import { Transform, Type } from "class-transformer"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
+import { EntityManager } from "typeorm"
 import { OrderService } from "../../../../services"
 import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
+
 /**
- * @oas [post] /orders/{id}/fulfillments
+ * @oas [post] /orders/{id}/fulfillment
  * operationId: "PostOrdersOrderFulfillments"
  * summary: "Create a Fulfillment"
  * description: "Creates a Fulfillment of an Order - will notify Fulfillment Providers to prepare a shipment."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -32,9 +34,12 @@ import { EntityManager } from "typeorm"
  *             description: The Line Items to include in the Fulfillment.
  *             type: array
  *             items:
+ *               required:
+ *                 - item_id
+ *                 - quantity
  *               properties:
  *                 item_id:
- *                   description: The id of Line Item to fulfill.
+ *                   description: The ID of Line Item to fulfill.
  *                   type: string
  *                 quantity:
  *                   description: The quantity of the Line Item to fulfill.
@@ -46,7 +51,7 @@ import { EntityManager } from "typeorm"
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
  * tags:
- *   - Order
+ *   - Fulfillment
  * responses:
  *   200:
  *     description: OK

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

@@ -5,11 +5,13 @@ import {
   IsOptional,
   IsString,
 } from "class-validator"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
-import { OrderService } from "../../../../services"
-import { validator } from "../../../../utils/validator"
-import { TrackingLink } from "../../../../models"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { OrderService } from "../../../../services"
+import { TrackingLink } from "../../../../models"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /orders/{id}/shipment
  * operationId: "PostOrdersOrderShipment"
@@ -17,7 +19,7 @@ import { EntityManager } from "typeorm"
  * description: "Registers a Fulfillment as shipped."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -26,7 +28,7 @@ import { EntityManager } from "typeorm"
  *           - fulfillment_id
  *         properties:
  *           fulfillment_id:
- *             description: The id of the Fulfillment.
+ *             description: The ID of the Fulfillment.
  *             type: string
  *           tracking_numbers:
  *             description: The tracking numbers for the shipment.

packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts

@@ -5,10 +5,12 @@ import {
   IsOptional,
   IsString,
 } from "class-validator"
-import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
 import { OrderService, SwapService } from "../../../../services"
-import { validator } from "../../../../utils/validator"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /orders/{id}/swaps/{swap_id}/shipments
  * operationId: "PostOrdersOrderSwapsSwapShipments"
@@ -16,8 +18,8 @@ import { EntityManager } from "typeorm"
  * description: "Registers a Swap Fulfillment as shipped."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) swap_id=* {string} The id of the Swap.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) swap_id=* {string} The ID of the Swap.
  * requestBody:
  *   content:
  *     application/json:
@@ -26,7 +28,7 @@ import { EntityManager } from "typeorm"
  *           - fulfillment_id
  *         properties:
  *           fulfillment_id:
- *             description: The id of the Fulfillment.
+ *             description: The ID of the Fulfillment.
  *             type: string
  *           tracking_numbers:
  *             description: The tracking numbers for the shipment.
@@ -37,7 +39,7 @@ import { EntityManager } from "typeorm"
  *             description: If set to true no notification will be send related to this Claim.
  *             type: boolean
  * tags:
- *   - Order
+ *   - Swap
  * responses:
  *   200:
  *     description: OK

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

@@ -1,26 +1,27 @@
-import { Type } from "class-transformer"
-import {
-  Min,
-  IsOptional,
-  IsArray,
-  IsString,
-  IsBoolean,
-  IsObject,
-  IsInt,
-  IsNotEmpty,
-  IsNumber,
-  ValidateNested,
-} from "class-validator"
-import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
 import {
   IdempotencyKeyService,
   OrderService,
   ReturnService,
   SwapService,
 } from "../../../../services"
-import { validator } from "../../../../utils/validator"
+import {
+  IsArray,
+  IsBoolean,
+  IsInt,
+  IsNotEmpty,
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  Min,
+  ValidateNested,
+} from "class-validator"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /order/{id}/swaps
@@ -29,7 +30,7 @@ import { EntityManager } from "typeorm"
  * description: "Creates a Swap. Swaps are used to handle Return of previously purchased goods and Fulfillment of replacements simultaneously."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -46,18 +47,26 @@ import { EntityManager } from "typeorm"
  *                 - quantity
  *               properties:
  *                 item_id:
- *                   description: The id of the Line Item that will be claimed.
+ *                   description: The ID of the Line Item that will be claimed.
  *                   type: string
  *                 quantity:
  *                   description: The number of items that will be returned
  *                   type: integer
+ *                 reason_id:
+ *                   description: The ID of the Return Reason to use.
+ *                   type: string
+ *                 note:
+ *                   description: An optional note with information about the Return.
+ *                   type: string
  *           return_shipping:
  *             description: How the Swap will be returned.
  *             type: object
+ *             required:
+ *               - option_id
  *             properties:
  *               option_id:
  *                 type: string
- *                 description: The id of the Shipping Option to create the Shipping Method from.
+ *                 description: The ID of the Shipping Option to create the Shipping Method from.
  *               price:
  *                 type: integer
  *                 description: The price to charge for the Shipping Method.
@@ -70,7 +79,7 @@ import { EntityManager } from "typeorm"
  *                 - quantity
  *               properties:
  *                 variant_id:
- *                   description: The id of the Product Variant to ship.
+ *                   description: The ID of the Product Variant to ship.
  *                   type: string
  *                 quantity:
  *                   description: The quantity of the Product Variant to ship.
@@ -84,7 +93,7 @@ import { EntityManager } from "typeorm"
  *                 - price
  *               properties:
  *                 option_id:
- *                   description: The id of the Shipping Option to override with a custom price.
+ *                   description: The ID of the Shipping Option to override with a custom price.
  *                   type: string
  *                 price:
  *                   description: The custom price of the Shipping Option.
@@ -95,8 +104,9 @@ import { EntityManager } from "typeorm"
  *           allow_backorder:
  *             description: If true, swaps can be completed with items out of stock
  *             type: boolean
+ *             default: true
  * tags:
- *   - Order
+ *   - Swap
  * responses:
  *   200:
  *     description: OK

packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts

@@ -1,8 +1,10 @@
-import { IsBoolean, IsObject, IsOptional } from "class-validator"
-import { EntityManager } from "typeorm"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import { ClaimService, OrderService } from "../../../../services"
+import { IsBoolean, IsObject, IsOptional } from "class-validator"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
+import { EntityManager } from "typeorm"
 import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /orders/{id}/claims/{claim_id}/fulfillments
  * operationId: "PostOrdersOrderClaimsClaimFulfillments"
@@ -10,8 +12,8 @@ import { validator } from "../../../../utils/validator"
  * description: "Creates a Fulfillment for a Claim."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) claim_id=* {string} The id of the Claim.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) claim_id=* {string} The ID of the Claim.
  * requestBody:
  *   content:
  *     application/json:
@@ -24,7 +26,7 @@ import { validator } from "../../../../utils/validator"
  *             description: If set to true no notification will be send related to this Claim.
  *             type: boolean
  * tags:
- *   - Order
+ *   - Fulfillment
  * responses:
  *   200:
  *     description: OK

packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts

@@ -1,8 +1,10 @@
 import { IsBoolean, IsObject, IsOptional } from "class-validator"
-import { EntityManager } from "typeorm"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
 import { OrderService, SwapService } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
+import { EntityManager } from "typeorm"
 import { validator } from "../../../../utils/validator"
+
 /**
  * @oas [post] /orders/{id}/swaps/{swap_id}/fulfillments
  * operationId: "PostOrdersOrderSwapsSwapFulfillments"
@@ -10,8 +12,8 @@ import { validator } from "../../../../utils/validator"
  * description: "Creates a Fulfillment for a Swap."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) swap_id=* {string} The id of the Swap.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) swap_id=* {string} The ID of the Swap.
  * requestBody:
  *   content:
  *     application/json:
@@ -24,7 +26,7 @@ import { validator } from "../../../../utils/validator"
  *             description: If set to true no notification will be send related to this Claim.
  *             type: boolean
  * tags:
- *   - Order
+ *   - Fulfillment
  * responses:
  *   200:
  *     description: OK

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

@@ -7,7 +7,7 @@ import { OrderService } from "../../../../services"
  * description: "Retrieves an Order"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * tags:
  *   - Order
  * responses:

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

@@ -1,9 +1,10 @@
 import { IsNumber, IsOptional, IsString } from "class-validator"
-import { pick } from "lodash"
-import { OrderService } from "../../../../services"
+
 import { AdminListOrdersSelector } from "../../../../types/orders"
-import { Type } from "class-transformer"
 import { Order } from "../../../../models"
+import { OrderService } from "../../../../services"
+import { Type } from "class-transformer"
+import { pick } from "lodash"
 
 /**
  * @oas [get] /orders
@@ -12,24 +13,144 @@ import { Order } from "../../../../models"
  * description: "Retrieves a list of Orders"
  * x-authenticated: true
  * parameters:
- *   - (query) q {string} Query used for searching orders.
- *   - (query) id {string} Id of the order to search for.
- *   - (query) status {string[]} Status to search for.
- *   - (query) fulfillment_status {string[]} Fulfillment status to search for.
- *   - (query) payment_status {string[]} Payment status to search for.
- *   - (query) display_id {string} Display id to search for.
+ *   - (query) q {string} Query used for searching orders by shipping address first name, orders' email, and orders' display ID
+ *   - (query) id {string} ID of the order to search for.
+ *   - in: query
+ *     name: status
+ *     style: form
+ *     explode: false
+ *     description: Status to search for
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
+ *         enum: [pending, completed, archived, canceled, requires_action]
+ *   - in: query
+ *     name: fulfillment_status
+ *     style: form
+ *     explode: false
+ *     description: Fulfillment status to search for.
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
+ *         enum: [not_fulfilled, fulfilled, partially_fulfilled, shipped, partially_shipped, canceled, returned, partially_returned, requires_action]
+ *   - in: query
+ *     name: payment_status
+ *     style: form
+ *     explode: false
+ *     description: Payment status to search for.
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
+ *         enum: [captured, awaiting, not_paid, refunded, partially_refunded, canceled, requires_action]
+ *   - (query) display_id {string} Display ID to search for.
  *   - (query) cart_id {string} to search for.
  *   - (query) customer_id {string} to search for.
  *   - (query) email {string} to search for.
- *   - (query) region_id {string} to search for.
- *   - (query) currency_code {string} to search for.
+ *   - in: query
+ *     name: region_id
+ *     style: form
+ *     explode: false
+ *     description: Regions to search orders by
+ *     schema:
+ *       oneOf:
+ *         - type: string
+ *           description: ID of a Region.
+ *         - type: array
+ *           items:
+ *             type: string
+ *             description: ID of a Region.
+ *   - in: query
+ *     name: currency_code
+ *     style: form
+ *     explode: false
+ *     description: Currency code to search for
+ *     schema:
+ *       type: string
+ *       externalDocs:
+ *         url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *         description: See a list of codes.
  *   - (query) tax_rate {string} to search for.
- *   - (query) sales_chanel_id {string[]} to retrieve products in.
- *   - (query) cancelled_at {DateComparisonOperator} Date comparison for when resulting orders was cancelled, i.e. less than, greater than etc.
- *   - (query) created_at {DateComparisonOperator} Date comparison for when resulting orders was created, i.e. less than, greater than etc.
- *   - (query) updated_at {DateComparisonOperator} Date comparison for when resulting orders was updated, i.e. less than, greater than etc.
- *   - (query) offset {string} How many orders to skip in the result.
- *   - (query) limit {string} Limit the number of orders returned.
+ *   - in: query
+ *     name: created_at
+ *     description: Date comparison for when resulting orders were created.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: updated_at
+ *     description: Date comparison for when resulting orders were updated.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: canceled_at
+ *     description: Date comparison for when resulting orders were canceled.
+ *     schema:
+ *       type: object
+ *       properties:
+ *         lt:
+ *            type: string
+ *            description: filter by dates less than this date
+ *            format: date
+ *         gt:
+ *            type: string
+ *            description: filter by dates greater than this date
+ *            format: date
+ *         lte:
+ *            type: string
+ *            description: filter by dates less than or equal to this date
+ *            format: date
+ *         gte:
+ *            type: string
+ *            description: filter by dates greater than or equal to this date
+ *            format: date
+ *   - in: query
+ *     name: sales_channel_id
+ *     style: form
+ *     explode: false
+ *     description: Filter by Sales Channels
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string
+ *         description: The ID of a Sales Channel
+ *   - (query) offset=0 {integer} How many orders to skip before the results.
+ *   - (query) limit=50 {integer} Limit the number of orders returned.
  *   - (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.
  * tags:
@@ -45,6 +166,15 @@ import { Order } from "../../../../models"
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/order"
+ *             count:
+ *               type: integer
+ *               description: The total number of items available
+ *             offset:
+ *               type: integer
+ *               description: The number of items skipped before these items
+ *             limit:
+ *               type: integer
+ *               description: The number of items per page
  */
 export default async (req, res) => {
   const orderService: OrderService = req.scope.resolve("orderService")

packages/medusa/src/api/routes/admin/orders/process-swap-payment.ts

@@ -1,6 +1,7 @@
-import { EntityManager } from "typeorm"
-import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
 import { OrderService, SwapService } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
+import { EntityManager } from "typeorm"
 
 /**
  * @oas [post] /orders/{id}/swaps/{swap_id}/process-payment
@@ -9,10 +10,10 @@ import { OrderService, SwapService } from "../../../../services"
  * description: "When there are differences between the returned and shipped Products in a Swap, the difference must be processed. Either a Refund will be issued or a Payment will be captured."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) swap_id=* {string} The id of the Swap.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) swap_id=* {string} The ID of the Swap.
  * tags:
- *   - Order
+ *   - Swap
  * responses:
  *   200:
  *     description: OK

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

@@ -5,19 +5,20 @@ import {
   IsOptional,
   IsString,
 } from "class-validator"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { OrderService } from "../../../../services"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
 /**
- * @oas [post] /orders/{id}/refunds
+ * @oas [post] /orders/{id}/refund
  * operationId: "PostOrdersOrderRefunds"
  * summary: "Create a Refund"
  * description: "Issues a Refund."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -33,7 +34,7 @@ import { EntityManager } from "typeorm"
  *             description: The reason for the Refund.
  *             type: string
  *           note:
- *             description: A not with additional details about the Refund.
+ *             description: A note with additional details about the Refund.
  *             type: string
  *           no_notification:
  *             description: If set to true no notification will be send related to this Refund.

packages/medusa/src/api/routes/admin/orders/request-return.ts

@@ -1,4 +1,8 @@
-import { Type } from "class-transformer"
+import {
+  EventBusService,
+  OrderService,
+  ReturnService,
+} from "../../../../services"
 import {
   IsArray,
   IsBoolean,
@@ -7,25 +11,22 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
 import { MedusaError } from "medusa-core-utils"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
-import {
-  EventBusService,
-  OrderService,
-  ReturnService,
-} from "../../../../services"
 import { OrdersReturnItem } from "../../../../types/orders"
+import { Type } from "class-transformer"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
 /**
- * @oas [post] /orders/{id}/returns
+ * @oas [post] /orders/{id}/return
  * operationId: "PostOrdersOrderReturns"
  * summary: "Request a Return"
  * description: "Requests a Return. If applicable a return label will be created and other plugins notified."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -37,12 +38,15 @@ import { EntityManager } from "typeorm"
  *             description: The Line Items that will be returned.
  *             type: array
  *             items:
+ *               required:
+ *                 - item_id
+ *                 - quantity
  *               properties:
  *                 item_id:
- *                   description: The id of the Line Item.
+ *                   description: The ID of the Line Item.
  *                   type: string
  *                 reason_id:
- *                   description: The id of the Return Reason to use.
+ *                   description: The ID of the Return Reason to use.
  *                   type: string
  *                 note:
  *                   description: An optional note with information about the Return.
@@ -56,13 +60,17 @@ import { EntityManager } from "typeorm"
  *             properties:
  *               option_id:
  *                 type: string
- *                 description: The id of the Shipping Option to create the Shipping Method from.
+ *                 description: The ID of the Shipping Option to create the Shipping Method from.
  *               price:
  *                 type: integer
  *                 description: The price to charge for the Shipping Method.
+ *           note:
+ *             description: An optional note with information about the Return.
+ *             type: string
  *           receive_now:
  *             description: A flag to indicate if the Return should be registerd as received immediately.
  *             type: boolean
+ *             default: false
  *           no_notification:
  *             description: A flag to indicate if no notifications should be emitted related to the requested Return.
  *             type: boolean
@@ -70,6 +78,7 @@ import { EntityManager } from "typeorm"
  *             description: The amount to refund.
  *             type: integer
  * tags:
+ *   - Return
  *   - Order
  * responses:
  *   200:

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

@@ -1,16 +1,17 @@
-import { Type } from "class-transformer"
+import { ClaimService, OrderService } from "../../../../services"
 import {
   IsArray,
-  ValidateNested,
-  IsOptional,
-  IsString,
   IsBoolean,
   IsInt,
   IsNotEmpty,
   IsObject,
+  IsOptional,
+  IsString,
+  ValidateNested,
 } from "class-validator"
-import { defaultAdminOrdersRelations, defaultAdminOrdersFields } from "."
-import { ClaimService, OrderService } from "../../../../services"
+import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
+
+import { Type } from "class-transformer"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -21,8 +22,8 @@ import { EntityManager } from "typeorm"
  * description: "Updates a Claim."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
- *   - (path) claim_id=* {string} The id of the Claim.
+ *   - (path) id=* {string} The ID of the Order.
+ *   - (path) claim_id=* {string} The ID of the Claim.
  * requestBody:
  *   content:
  *     application/json:
@@ -32,12 +33,16 @@ import { EntityManager } from "typeorm"
  *             description: The Claim Items that the Claim will consist of.
  *             type: array
  *             items:
+ *               required:
+ *                 - id
+ *                 - images
+ *                 - tags
  *               properties:
  *                 id:
- *                   description: The id of the Claim Item.
+ *                   description: The ID of the Claim Item.
  *                   type: string
  *                 item_id:
- *                   description: The id of the Line Item that will be claimed.
+ *                   description: The ID of the Line Item that will be claimed.
  *                   type: string
  *                 quantity:
  *                   description: The number of items that will be returned
@@ -57,21 +62,39 @@ import { EntityManager } from "typeorm"
  *                   description: A list o tags to add to the Claim Item
  *                   type: array
  *                   items:
- *                     type: string
+ *                     type: object
+ *                     properties:
+ *                       id:
+ *                         type: string
+ *                         description: Tag ID
+ *                       value:
+ *                         type: string
+ *                         description: Tag value
  *                 images:
  *                   description: A list of image URL's that will be associated with the Claim
+ *                   type: array
  *                   items:
- *                     type: string
+ *                     type: object
+ *                     properties:
+ *                       id:
+ *                         type: string
+ *                         description: Image ID
+ *                       url:
+ *                         type: string
+ *                         description: Image URL
+ *                 metadata:
+ *                   description: An optional set of key-value pairs to hold additional information.
+ *                   type: object
  *           shipping_methods:
  *             description: The Shipping Methods to send the additional Line Items with.
  *             type: array
  *             items:
  *                properties:
  *                  id:
- *                    description: The id of an existing Shipping Method
+ *                    description: The ID of an existing Shipping Method
  *                    type: string
  *                  option_id:
- *                    description: The id of the Shipping Option to create a Shipping Method from
+ *                    description: The ID of the Shipping Option to create a Shipping Method from
  *                    type: string
  *                  price:
  *                    description: The price to charge for the Shipping Method
@@ -83,7 +106,7 @@ import { EntityManager } from "typeorm"
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
  * tags:
- *   - Order
+ *   - Claim
  * responses:
  *   200:
  *     description: OK

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

@@ -1,4 +1,3 @@
-import { Type } from "class-transformer"
 import {
   IsArray,
   IsBoolean,
@@ -10,10 +9,12 @@ import {
   ValidateNested,
 } from "class-validator"
 import { defaultAdminOrdersFields, defaultAdminOrdersRelations } from "."
-import { OrderService } from "../../../../services"
+
 import { AddressPayload } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
+import { OrderService } from "../../../../services"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"
 
 /**
  * @oas [post] /orders/{id}
@@ -22,7 +23,7 @@ import { EntityManager } from "typeorm"
  * description: "Updates and order"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Order.
+ *   - (path) id=* {string} The ID of the Order.
  * requestBody:
  *   content:
  *     application/json:
@@ -34,51 +35,57 @@ import { EntityManager } from "typeorm"
  *           billing_address:
  *             description: Billing address
  *             anyOf:
- *               - $ref: "#/components/schemas/address
+ *               - $ref: "#/components/schemas/address"
  *           shipping_address:
  *             description: Shipping address
  *             anyOf:
- *               - $ref: "#/components/schemas/address
+ *               - $ref: "#/components/schemas/address"
  *           items:
  *             description: The Line Items for the order
  *             type: array
+ *             items:
+ *               $ref: "#/components/schemas/line_item"
  *           region:
- *             description: Region where the order belongs
+ *             description: ID of the region where the order belongs
  *             type: string
  *           discounts:
  *             description: Discounts applied to the order
  *             type: array
+ *             items:
+ *               $ref: "#/components/schemas/discount"
  *           customer_id:
- *             description: id of the customer
+ *             description: ID of the customer
  *             type: string
  *           payment_method:
- *             description:
- *             type: Record<string, unknown>
+ *             description: payment method chosen for the order
+ *             type: object
  *             properties:
  *               provider_id:
  *                 type: string
- *                 description: id of the payment provider
+ *                 description: ID of the payment provider
  *               data:
  *                 description: Data relevant for the given payment method
- *                 type: Record<string, unknown>
+ *                 type: object
  *           shipping_method:
  *             description: The Shipping Method used for shipping the order.
- *             type: Record<string, unknown>
+ *             type: object
  *             properties:
  *               provider_id:
  *                 type: string
- *                 description: The id of the shipping provider.
+ *                 description: The ID of the shipping provider.
  *               profile_id:
  *                 type: string
- *                 description: The id of the shipping profile.
+ *                 description: The ID of the shipping profile.
  *               price:
  *                 type: integer
  *                 description: The price of the shipping.
  *               data:
- *                 type: Record<string, unknown>
+ *                 type: object
  *                 description: Data relevant to the specific shipping method.
  *               items:
  *                 type: array
+ *                 items:
+ *                   $ref: "#/components/schemas/line_item"
  *                 description: Items to ship
  *           no_notification:
  *             description: A flag to indicate if no notifications should be emitted related to the updated order.

packages/medusa/src/api/routes/admin/price-lists/add-prices-batch.ts

@@ -1,9 +1,10 @@
-import { Type } from "class-transformer"
 import { IsArray, IsBoolean, IsOptional, ValidateNested } from "class-validator"
 import { defaultAdminPriceListFields, defaultAdminPriceListRelations } from "."
+
+import { AdminPriceListPricesUpdateReq } from "../../../../types/price-list"
 import { PriceList } from "../../../.."
 import PriceListService from "../../../../services/price-list"
-import { AdminPriceListPricesUpdateReq } from "../../../../types/price-list"
+import { Type } from "class-transformer"
 import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
 
@@ -14,44 +15,47 @@ import { EntityManager } from "typeorm"
  * description: "Batch update prices for a Price List"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Price List to update prices for.
+ *   - (path) id=* {string} The ID of the Price List to update prices for.
  * requestBody:
  *  content:
- *   application/json:
- *   schema:
- *     properties:
- *       prices:
- *         description: The prices to update or add.
- *         type: array
- *         items:
- *           properties:
- *             id:
- *               description: The id of the price.
- *               type: string
- *             status:
- *               description: The status of the Price List.
- *               type: string
- *               enum:
- *                 - active
- *                 - draft
- *            region_id:
- *              description: The id of the Region for which the price is used.
- *              type: string
- *            currency_code:
- *              description: The 3 character ISO currency code for which the price will be used.
- *              type: string
- *            amount:
- *              description: The amount of the price.
- *              type: number
- *            min_quantity:
- *              description: The minimum quantity for which the price will be used.
- *              type: number
- *            max_quantity:
- *             description: The maximum quantity for which the price will be used.
- *             type: number
- *       override:
- *         description: "If true the prices will replace all existing prices associated with the Price List."
- *         type: boolean
+ *    application/json:
+ *      schema:
+ *        properties:
+ *          prices:
+ *            description: The prices to update or add.
+ *            type: array
+ *            items:
+ *              required:
+ *                - amount
+ *                - variant_id
+ *              properties:
+ *                id:
+ *                  description: The ID of the price.
+ *                  type: string
+ *                region_id:
+ *                  description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
+ *                  type: string
+ *                currency_code:
+ *                  description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *                  type: string
+ *                  externalDocs:
+ *                    url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *                    description: See a list of codes.
+ *                variant_id:
+ *                  description: The ID of the Variant for which the price is used.
+ *                  type: string
+ *                amount:
+ *                  description: The amount to charge for the Product Variant.
+ *                  type: integer
+ *                min_quantity:
+ *                  description: The minimum quantity for which the price will be used.
+ *                  type: integer
+ *                max_quantity:
+ *                  description: The maximum quantity for which the price will be used.
+ *                  type: integer
+ *          override:
+ *            description: "If true the prices will replace all existing prices associated with the Price List."
+ *            type: boolean
  * tags:
  *   - Price List
  * responses:
@@ -61,14 +65,8 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             id:
- *               type: string
- *               description: The id of the deleted Price List.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *             deleted:
- *               type: boolean
+ *             price_list:
+ *               $ref: "#/components/schemas/price_list"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/price-lists/create-price-list.ts

@@ -1,4 +1,9 @@
-import { Type } from "class-transformer"
+import {
+  AdminPriceListPricesCreateReq,
+  CreatePriceListInput,
+  PriceListStatus,
+  PriceListType,
+} from "../../../../types/price-list"
 import {
   IsArray,
   IsEnum,
@@ -6,18 +11,14 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import PriceListService from "../../../../services/price-list"
-import {
-  AdminPriceListPricesCreateReq,
-  CreatePriceListInput,
-  PriceListStatus,
-  PriceListType,
-} from "../../../../types/price-list"
-import { Request } from "express"
+
 import { EntityManager } from "typeorm"
+import PriceListService from "../../../../services/price-list"
+import { Request } from "express"
+import { Type } from "class-transformer"
 
 /**
- * @oas [post] /price_lists
+ * @oas [post] /price-lists
  * operationId: "PostPriceListsPriceList"
  * summary: "Creates a Price List"
  * description: "Creates a Price List"
@@ -26,6 +27,11 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
+ *         required:
+ *           - name
+ *           - description
+ *           - type
+ *           - prices
  *         properties:
  *           name:
  *             description: "The name of the Price List"
@@ -33,47 +39,64 @@ import { EntityManager } from "typeorm"
  *           description:
  *             description: "A description of the Price List."
  *             type: string
+ *           starts_at:
+ *             description: "The date with timezone that the Price List starts being valid."
+ *             type: string
+ *             format: date
+ *           ends_at:
+ *             description: "The date with timezone that the Price List ends being valid."
+ *             type: string
+ *             format: date
  *           type:
  *             description: The type of the Price List.
  *             type: string
  *             enum:
  *              - sale
  *              - override
- *          status:
- *            description: The status of the Price List.
- *            type: string
- *            enum:
- *             - active
- *             - draft
- *          prices:
- *            description: The prices of the Price List.
- *            type: array
- *            items:
- *              properties:
- *                region_id:
- *                  description: The id of the Region for which the price is used.
- *                  type: string
- *                currency_code:
- *                  description: The 3 character ISO currency code for which the price will be used.
- *                  type: string
- *                amount:
- *                  description: The amount to charge for the Product Variant.
- *                  type: integer
- *                min_quantity:
- *                  description: The minimum quantity for which the price will be used.
- *                  type: integer
- *                max_quantity:
- *                  description: The maximum quantity for which the price will be used.
- *                  type: integer
- *          customer_groups:
- *            type: array
+ *           status:
+ *             description: The status of the Price List.
+ *             type: string
+ *             enum:
+ *               - active
+ *               - draft
+ *           prices:
+ *              description: The prices of the Price List.
+ *              type: array
+ *              items:
+ *                required:
+ *                  - amount
+ *                  - variant_id
+ *                properties:
+ *                  region_id:
+ *                    description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
+ *                    type: string
+ *                  currency_code:
+ *                    description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *                    type: string
+ *                    externalDocs:
+ *                      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *                      description: See a list of codes.
+ *                  amount:
+ *                    description: The amount to charge for the Product Variant.
+ *                    type: integer
+ *                  variant_id:
+ *                    description: The ID of the Variant for which the price is used.
+ *                    type: string
+ *                  min_quantity:
+ *                    description: The minimum quantity for which the price will be used.
+ *                    type: integer
+ *                  max_quantity:
+ *                    description: The maximum quantity for which the price will be used.
+ *                    type: integer
+ *           customer_groups:
+ *             type: array
  *             description: A list of customer groups that the Price List applies to.
  *             items:
  *               required:
  *                 - id
  *               properties:
  *                 id:
- *                   description: The id of a customer group
+ *                   description: The ID of a customer group
  *                   type: string
  * tags:
  *   - Price List
@@ -84,7 +107,7 @@ import { EntityManager } from "typeorm"
  *       application/json:
  *         schema:
  *           properties:
- *             product:
+ *             price_list:
  *               $ref: "#/components/schemas/price_list"
  */
 export default async (req: Request, res) => {

packages/medusa/src/api/routes/admin/price-lists/delete-price-list.ts

@@ -1,5 +1,5 @@
-import PriceListService from "../../../../services/price-list"
 import { EntityManager } from "typeorm"
+import PriceListService from "../../../../services/price-list"
 
 /**
  * @oas [delete] /price-lists/{id}
@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * description: "Deletes a Price List"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Price List to delete.
+ *   - (path) id=* {string} The ID of the Price List to delete.
  * tags:
  *   - Price List
  * responses:
@@ -20,12 +20,15 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             id:
  *               type: string
- *               description: The id of the deleted Price List.
+ *               description: The ID of the deleted Price List.
  *             object:
  *               type: string
  *               description: The type of the object that was deleted.
+ *               default: price-list
  *             deleted:
  *               type: boolean
+ *               description: Whether or not the items were deleted.
+ *               default: true
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/price-lists/delete-prices-batch.ts

@@ -1,26 +1,27 @@
 import { ArrayNotEmpty, IsString } from "class-validator"
+
+import { EntityManager } from "typeorm"
 import PriceListService from "../../../../services/price-list"
 import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
 
 /**
  * @oas [delete] /price-lists/{id}/prices/batch
  * operationId: "DeletePriceListsPriceListPricesBatch"
- * summary: "Batch delete prices that belongs to a Price List"
- * description: "Batch delete prices that belongs to a Price List"
+ * summary: "Batch delete prices that belong to a Price List"
+ * description: "Batch delete prices that belong to a Price List"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Price List that the Money Amounts that will be deleted belongs to.
+ *   - (path) id=* {string} The ID of the Price List that the Money Amounts (Prices) that will be deleted belongs to.
  * requestBody:
- *  content:
- *   application/json:
- *   schema:
- *    properties:
- *      price_ids:
- *        description: The price id's of the Money Amounts to delete.
- *        type: array
- *        items:
- *          type: string
+ *   content:
+ *     application/json:
+ *       schema:
+ *         properties:
+ *           price_ids:
+ *             description: The price id's of the Money Amounts to delete.
+ *             type: array
+ *             items:
+ *               type: string
  * tags:
  *   - Price List
  * responses:
@@ -34,12 +35,15 @@ import { EntityManager } from "typeorm"
  *               type: array
  *               items:
  *                 type: string
- *                 description: The id of the deleted Money Amount.
+ *                 description: The IDs of the deleted Money Amounts (Prices).
  *             object:
  *               type: string
  *               description: The type of the object that was deleted.
+ *               default: money-amount
  *             deleted:
  *               type: boolean
+ *               description: Whether or not the items were deleted.
+ *               default: true
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/price-lists/delete-product-prices.ts

@@ -1,5 +1,5 @@
-import PriceListService from "../../../../services/price-list"
 import { EntityManager } from "typeorm"
+import PriceListService from "../../../../services/price-list"
 
 /**
  * @oas [delete] /price-lists/{id}/products/{product_id}/prices
@@ -8,8 +8,8 @@ import { EntityManager } from "typeorm"
  * description: "Delete all the prices related to a specific product in a price list"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Price List that the Money Amounts that will be deleted belongs to.
- *   - (path) product_id=* {string} The id of the product from which the money amount will be deleted.
+ *   - (path) id=* {string} The ID of the Price List that the Money Amounts that will be deleted belongs to.
+ *   - (path) product_id=* {string} The ID of the product from which the money amount will be deleted.
  * tags:
  *   - Price List
  * responses:
@@ -20,16 +20,18 @@ import { EntityManager } from "typeorm"
  *         schema:
  *           properties:
  *              ids:
- *               type: number
+ *               type: array
  *               description: The price ids that have been deleted.
- *             count:
- *               type: number
- *               description: The number of prices that have been deleted.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *             deleted:
- *               type: boolean
+ *               items:
+ *                 type: string
+ *              object:
+ *                type: string
+ *                description: The type of the object that was deleted.
+ *                default: money-amount
+ *              deleted:
+ *                type: boolean
+ *                description: Whether or not the items were deleted.
+ *                default: true
  */
 export default async (req, res) => {
   const { id, product_id } = req.params

packages/medusa/src/api/routes/admin/price-lists/delete-variant-prices.ts

@@ -1,5 +1,5 @@
-import PriceListService from "../../../../services/price-list"
 import { EntityManager } from "typeorm"
+import PriceListService from "../../../../services/price-list"
 
 /**
  * @oas [delete] /price-lists/{id}/variants/{variant_id}/prices
@@ -8,8 +8,8 @@ import { EntityManager } from "typeorm"
  * description: "Delete all the prices related to a specific variant in a price list"
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Price List that the Money Amounts that will be deleted belongs to.
- *   - (path) variant_id=* {string} The id of the variant from which the money amount will be deleted.
+ *   - (path) id=* {string} The ID of the Price List that the Money Amounts that will be deleted belongs to.
+ *   - (path) variant_id=* {string} The ID of the variant from which the money amount will be deleted.
  * tags:
  *   - Price List
  * responses:
@@ -20,16 +20,18 @@ import { EntityManager } from "typeorm"
  *         schema:
  *           properties:
  *              ids:
- *               type: number
+ *               type: array
  *               description: The price ids that have been deleted.
- *             count:
- *               type: number
- *               description: The number of prices that have been deleted.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *             deleted:
- *               type: boolean
+ *               items:
+ *                 type: string
+ *              object:
+ *                type: string
+ *                description: The type of the object that was deleted.
+ *                default: money-amount
+ *              deleted:
+ *                type: boolean
+ *                description: Whether or not the items were deleted.
+ *                default: true
  */
 export default async (req, res) => {
   const { id, variant_id } = req.params

packages/medusa/src/api/routes/admin/price-lists/get-price-list.ts

@@ -1,4 +1,5 @@
 import { defaultAdminPriceListFields, defaultAdminPriceListRelations } from "."
+
 import { PriceList } from "../../../.."
 import PriceListService from "../../../../services/price-list"
 
@@ -9,7 +10,7 @@ import PriceListService from "../../../../services/price-list"
  * description: "Retrieves a Price List."
  * x-authenticated: true
  * parameters:
- *   - (path) id=* {string} The id of the Price List.
+ *   - (path) id=* {string} The ID of the Price List.
  * tags:
  *   - Price List
  * responses: