diff --git a/.changeset/spicy-windows-invent.md b/.changeset/spicy-windows-invent.md
new file mode 100644
index 0000000000..a6a9b7aa49
--- /dev/null
+++ b/.changeset/spicy-windows-invent.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Store PRO-V)
diff --git a/packages/medusa/src/api/routes/admin/products/index.ts b/packages/medusa/src/api/routes/admin/products/index.ts
index 1d135d4123..8db38ebd8e 100644
--- a/packages/medusa/src/api/routes/admin/products/index.ts
+++ b/packages/medusa/src/api/routes/admin/products/index.ts
@@ -211,7 +211,9 @@ export type AdminProductsDeleteRes = {
  *   products:
  *     type: array
  *     items:
- *       $ref: "#/components/schemas/Product"
+ *       oneOf:
+ *         - $ref: "#/components/schemas/Product"
+ *         - $ref: "#/components/schemas/PricedProduct"
  *   count:
  *     type: integer
  *     description: The total number of items available
diff --git a/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts b/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts
index 060b766279..509b242fec 100644
--- a/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts
+++ b/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts
@@ -3,7 +3,7 @@ import { Request, Response } from "express"
 import ProductCategoryService from "../../../../services/product-category"
 import { FindParams } from "../../../../types/common"
 import { transformTreeNodesWithConfig } from "../../../../utils/transformers/tree"
-import { defaultStoreProductCategoryRelations, defaultStoreScope } from "."
+import { defaultStoreScope } from "."
 
 /**
  * @oas [get] /product-categories/{id}
@@ -42,10 +42,7 @@ import { defaultStoreProductCategoryRelations, defaultStoreScope } from "."
  *    content:
  *      application/json:
  *        schema:
- *          type: object
- *          properties:
- *            productCategory:
- *              $ref: "#/components/schemas/ProductCategory"
+ *          $ref: "#/components/schemas/StoreGetProductCategoryRes"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":
diff --git a/packages/medusa/src/api/routes/store/product-categories/index.ts b/packages/medusa/src/api/routes/store/product-categories/index.ts
index 299925ec1f..99ce350044 100644
--- a/packages/medusa/src/api/routes/store/product-categories/index.ts
+++ b/packages/medusa/src/api/routes/store/product-categories/index.ts
@@ -3,6 +3,7 @@ import middlewares, { transformQuery } from "../../../middlewares"
 import getProductCategory, {
   StoreGetProductCategoryParams,
 } from "./get-product-category"
+import { ProductCategory } from "../../../../models"
 
 import listProductCategories, {
   StoreGetProductCategoriesParams,
@@ -66,5 +67,16 @@ export const allowedStoreProductCategoryFields = [
   "updated_at",
 ]
 
+/**
+ * @schema StoreGetProductCategoryRes
+ * type: object
+ * properties:
+ *   product_category:
+ *     $ref: "#/components/schemas/ProductCategory"
+ */
+export type StoreGetProductCategoryRes = {
+  product_category: ProductCategory
+}
+
 export * from "./get-product-category"
 export * from "./list-product-categories"
diff --git a/packages/medusa/src/api/routes/store/product-types/index.ts b/packages/medusa/src/api/routes/store/product-types/index.ts
index a55ba436c1..fae449a4b3 100644
--- a/packages/medusa/src/api/routes/store/product-types/index.ts
+++ b/packages/medusa/src/api/routes/store/product-types/index.ts
@@ -39,12 +39,26 @@ export const defaultStoreProductTypeFields = [
 ]
 export const defaultStoreProductTypeRelations = []
 
+/**
+ * @schema StoreProductTypesListRes
+ * type: object
+ * properties:
+ *   product_types:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ProductType"
+ *   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 type StoreProductTypesListRes = PaginatedResponse & {
   product_types: ProductType[]
 }
 
-export type StoreProductTypesRes = {
-  product_type: ProductType
-}
-
 export * from "./list-product-types"
diff --git a/packages/medusa/src/api/routes/store/product-types/list-product-types.ts b/packages/medusa/src/api/routes/store/product-types/list-product-types.ts
index 6a760cad7a..a7451dcc2e 100644
--- a/packages/medusa/src/api/routes/store/product-types/list-product-types.ts
+++ b/packages/medusa/src/api/routes/store/product-types/list-product-types.ts
@@ -109,19 +109,7 @@ import ProductTypeService from "../../../../services/product-type"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
- *          properties:
- *            product_types:
- *              $ref: "#/components/schemas/ProductType"
- *            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
+ *          $ref: "#/components/schemas/StoreProductTypesListRes"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":
diff --git a/packages/medusa/src/api/routes/store/products/get-product.ts b/packages/medusa/src/api/routes/store/products/get-product.ts
index 65acdd6bb4..456cd20865 100644
--- a/packages/medusa/src/api/routes/store/products/get-product.ts
+++ b/packages/medusa/src/api/routes/store/products/get-product.ts
@@ -49,19 +49,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             product:
- *               allOf:
- *                 - $ref: "#/components/schemas/Product"
- *                 - type: object
- *                   properties:
- *                     variants:
- *                       type: array
- *                       items:
- *                         allOf:
- *                           - $ref: "#/components/schemas/ProductVariant"
- *                           - $ref: "#/components/schemas/ProductVariantPricesFields"
+ *           $ref: "#/components/schemas/StoreProductsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/products/index.ts b/packages/medusa/src/api/routes/store/products/index.ts
index 6f875e127c..3f9e570adf 100644
--- a/packages/medusa/src/api/routes/store/products/index.ts
+++ b/packages/medusa/src/api/routes/store/products/index.ts
@@ -54,15 +54,48 @@ export const defaultStoreProductsRelations = [
 export * from "./list-products"
 export * from "./search"
 
+/**
+ * @schema StoreProductsRes
+ * type: object
+ * properties:
+ *   product:
+ *     $ref: "#/components/schemas/PricedProduct"
+ */
 export type StoreProductsRes = {
   product: Product
 }
 
+/**
+ * @schema StorePostSearchRes
+ * type: object
+ * properties:
+ *   hits:
+ *     type: array
+ *     description: Array of results. The format of the items depends on the search engine installed on the server.
+ */
 export type StorePostSearchRes = {
   hits: unknown[]
   [k: string]: unknown
 }
 
+/**
+ * @schema StoreProductsListRes
+ * type: object
+ * properties:
+ *   products:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/PricedProduct"
+ *   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 type StoreProductsListRes = PaginatedResponse & {
   products: Product[]
 }
diff --git a/packages/medusa/src/api/routes/store/products/list-products.ts b/packages/medusa/src/api/routes/store/products/list-products.ts
index 673367d893..1c46d9cf97 100644
--- a/packages/medusa/src/api/routes/store/products/list-products.ts
+++ b/packages/medusa/src/api/routes/store/products/list-products.ts
@@ -151,30 +151,7 @@ import PublishableAPIKeysFeatureFlag from "../../../../loaders/feature-flags/pub
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             products:
- *               type: array
- *               items:
- *                 allOf:
- *                   - $ref: "#/components/schemas/Product"
- *                   - type: object
- *                     properties:
- *                       variants:
- *                         type: array
- *                         items:
- *                           allOf:
- *                             - $ref: "#/components/schemas/ProductVariant"
- *                             - $ref: "#/components/schemas/ProductVariantPricesFields"
- *             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
+ *           $ref: "#/components/schemas/StoreProductsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/products/search.ts b/packages/medusa/src/api/routes/store/products/search.ts
index fba21e95bf..42e390e624 100644
--- a/packages/medusa/src/api/routes/store/products/search.ts
+++ b/packages/medusa/src/api/routes/store/products/search.ts
@@ -39,11 +39,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             hits:
- *               type: array
- *               description: Array of results. The format of the items depends on the search engine installed on the server.
+ *           $ref: "#/components/schemas/StorePostSearchRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/regions/get-region.ts b/packages/medusa/src/api/routes/store/regions/get-region.ts
index 65f869be2a..fcff4d9081 100644
--- a/packages/medusa/src/api/routes/store/regions/get-region.ts
+++ b/packages/medusa/src/api/routes/store/regions/get-region.ts
@@ -29,10 +29,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/StoreRegionsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/regions/index.ts b/packages/medusa/src/api/routes/store/regions/index.ts
index 5b40d13796..420783ad64 100644
--- a/packages/medusa/src/api/routes/store/regions/index.ts
+++ b/packages/medusa/src/api/routes/store/regions/index.ts
@@ -13,10 +13,26 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema StoreRegionsListRes
+ * type: object
+ * properties:
+ *   regions:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Region"
+ */
 export type StoreRegionsListRes = {
   regions: Region[]
 }
 
+/**
+ * @schema StoreRegionsRes
+ * type: object
+ * properties:
+ *   region:
+ *     $ref: "#/components/schemas/Region"
+ */
 export type StoreRegionsRes = {
   region: Region
 }
diff --git a/packages/medusa/src/api/routes/store/regions/list-regions.ts b/packages/medusa/src/api/routes/store/regions/list-regions.ts
index fc7d48121c..2b0a234312 100644
--- a/packages/medusa/src/api/routes/store/regions/list-regions.ts
+++ b/packages/medusa/src/api/routes/store/regions/list-regions.ts
@@ -80,12 +80,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             regions:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/StoreRegionsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts b/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts
index dd93b41566..ec3570ad92 100644
--- a/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts
+++ b/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts
@@ -33,10 +33,7 @@ import ReturnReasonService from "../../../../services/return-reason"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/StoreReturnReasonsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/return-reasons/index.ts b/packages/medusa/src/api/routes/store/return-reasons/index.ts
index bd2ef8e560..47484a5351 100644
--- a/packages/medusa/src/api/routes/store/return-reasons/index.ts
+++ b/packages/medusa/src/api/routes/store/return-reasons/index.ts
@@ -36,10 +36,26 @@ export const defaultStoreReturnReasonRelations: (keyof ReturnReason)[] = [
   "return_reason_children",
 ]
 
+/**
+ * @schema StoreReturnReasonsListRes
+ * type: object
+ * properties:
+ *   return_reasons:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ReturnReason"
+ */
 export type StoreReturnReasonsListRes = {
   return_reasons: ReturnReason[]
 }
 
+/**
+ * @schema StoreReturnReasonsRes
+ * type: object
+ * properties:
+ *   return_reason:
+ *     $ref: "#/components/schemas/ReturnReason"
+ */
 export type StoreReturnReasonsRes = {
   return_reason: ReturnReason
 }
diff --git a/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts b/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts
index 4b65031d96..9a3bfa8e98 100644
--- a/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts
+++ b/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts
@@ -31,12 +31,7 @@ import ReturnReasonService from "../../../../services/return-reason"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             return_reasons:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/StoreReturnReasonsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/returns/create-return.ts b/packages/medusa/src/api/routes/store/returns/create-return.ts
index ce5a7f1821..f73992acc5 100644
--- a/packages/medusa/src/api/routes/store/returns/create-return.ts
+++ b/packages/medusa/src/api/routes/store/returns/create-return.ts
@@ -66,10 +66,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             return:
- *               $ref: "#/components/schemas/Return"
+ *           $ref: "#/components/schemas/StoreReturnsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/returns/index.ts b/packages/medusa/src/api/routes/store/returns/index.ts
index d1bb7a1cfc..51aaa7709e 100644
--- a/packages/medusa/src/api/routes/store/returns/index.ts
+++ b/packages/medusa/src/api/routes/store/returns/index.ts
@@ -12,6 +12,13 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema StoreReturnsRes
+ * type: object
+ * properties:
+ *   return:
+ *     $ref: "#/components/schemas/Return"
+ */
 export type StoreReturnsRes = {
   return: Return
 }
diff --git a/packages/medusa/src/api/routes/store/shipping-options/index.ts b/packages/medusa/src/api/routes/store/shipping-options/index.ts
index 4632f7718c..3d28d386a3 100644
--- a/packages/medusa/src/api/routes/store/shipping-options/index.ts
+++ b/packages/medusa/src/api/routes/store/shipping-options/index.ts
@@ -16,6 +16,15 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema StoreShippingOptionsListRes
+ * type: object
+ * properties:
+ *   shipping_options:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ShippingOption"
+ */
 export type StoreShippingOptionsListRes = {
   shipping_options: ShippingOption[]
 }
diff --git a/packages/medusa/src/api/routes/store/shipping-options/list-options.ts b/packages/medusa/src/api/routes/store/shipping-options/list-options.ts
index 2a6a0e17a6..a2180d4950 100644
--- a/packages/medusa/src/api/routes/store/shipping-options/list-options.ts
+++ b/packages/medusa/src/api/routes/store/shipping-options/list-options.ts
@@ -34,12 +34,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/StoreShippingOptionsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts b/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts
index 8ee27bde09..4ff7bc33ec 100644
--- a/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts
+++ b/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts
@@ -30,12 +30,7 @@ import ShippingProfileService from "../../../../services/shipping-profile"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/StoreShippingOptionsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/swaps/create-swap.ts b/packages/medusa/src/api/routes/store/swaps/create-swap.ts
index 146ed54825..77be708ba2 100644
--- a/packages/medusa/src/api/routes/store/swaps/create-swap.ts
+++ b/packages/medusa/src/api/routes/store/swaps/create-swap.ts
@@ -80,10 +80,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             swap:
- *               $ref: "#/components/schemas/Swap"
+ *           $ref: "#/components/schemas/StoreSwapsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts b/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts
index 1544acdde0..12716226ac 100644
--- a/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts
+++ b/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts
@@ -29,10 +29,7 @@ import SwapService from "../../../../services/swap"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             swap:
- *               $ref: "#/components/schemas/Swap"
+ *           $ref: "#/components/schemas/StoreSwapsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/swaps/index.ts b/packages/medusa/src/api/routes/store/swaps/index.ts
index 2f7fbc1152..38880c59cc 100644
--- a/packages/medusa/src/api/routes/store/swaps/index.ts
+++ b/packages/medusa/src/api/routes/store/swaps/index.ts
@@ -45,6 +45,13 @@ export const defaultStoreSwapFields: FindConfig<Swap>["select"] = [
   "idempotency_key",
 ]
 
+/**
+ * @schema StoreSwapsRes
+ * type: object
+ * properties:
+ *   swap:
+ *     $ref: "#/components/schemas/Swap"
+ */
 export type StoreSwapsRes = {
   swap: Swap
 }
diff --git a/packages/medusa/src/api/routes/store/variants/get-variant.ts b/packages/medusa/src/api/routes/store/variants/get-variant.ts
index d5414559fb..99de63e62d 100644
--- a/packages/medusa/src/api/routes/store/variants/get-variant.ts
+++ b/packages/medusa/src/api/routes/store/variants/get-variant.ts
@@ -41,12 +41,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             variant:
- *               allOf:
- *                 - $ref: "#/components/schemas/ProductVariant"
- *                 - $ref: "#/components/schemas/ProductVariantPricesFields"
+ *           $ref: "#/components/schemas/StoreVariantsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/api/routes/store/variants/index.ts b/packages/medusa/src/api/routes/store/variants/index.ts
index 8318a1eea8..f972cc1cf5 100644
--- a/packages/medusa/src/api/routes/store/variants/index.ts
+++ b/packages/medusa/src/api/routes/store/variants/index.ts
@@ -1,4 +1,3 @@
-import { PaginatedResponse } from "./../../../../types/common"
 import { ProductVariant } from "../../../../"
 import { Router } from "express"
 import middlewares from "../../../middlewares"
@@ -16,11 +15,27 @@ export default (app) => {
 
 export const defaultStoreVariantRelations = ["prices", "options"]
 
+/**
+ * @schema StoreVariantsRes
+ * type: object
+ * properties:
+ *   variant:
+ *     $ref: "#/components/schemas/PricedVariant"
+ */
 export type StoreVariantsRes = {
   variant: ProductVariant
 }
 
-export type StoreVariantsListRes = PaginatedResponse & {
+/**
+ * @schema StoreVariantsListRes
+ * type: object
+ * properties:
+ *   variants:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/PricedVariant"
+ */
+export type StoreVariantsListRes = {
   variants: ProductVariant[]
 }
 
diff --git a/packages/medusa/src/api/routes/store/variants/list-variants.ts b/packages/medusa/src/api/routes/store/variants/list-variants.ts
index 0e271e2f56..b6eb114b89 100644
--- a/packages/medusa/src/api/routes/store/variants/list-variants.ts
+++ b/packages/medusa/src/api/routes/store/variants/list-variants.ts
@@ -73,14 +73,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             variants:
- *               type: array
- *               items:
- *                 allOf:
- *                   - $ref: "#/components/schemas/ProductVariant"
- *                   - $ref: "#/components/schemas/ProductVariantPricesFields"
+ *           $ref: "#/components/schemas/StoreVariantsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":
diff --git a/packages/medusa/src/models/product-variant.ts b/packages/medusa/src/models/product-variant.ts
index 41e307166e..c8a2221dec 100644
--- a/packages/medusa/src/models/product-variant.ts
+++ b/packages/medusa/src/models/product-variant.ts
@@ -216,44 +216,3 @@ export class ProductVariant extends SoftDeletableEntity {
  *     description: An optional key-value map with additional details
  *     example: {car: "white"}
  */
-
-/**
- * @schema ProductVariantPricesFields
- * title: "Product Variant Prices Fields"
- * description: "Product Variants Prices Fields that are only available in some requests."
- * type: object
- * properties:
- *   original_price:
- *     type: number
- *     description: The original price of the variant without any discounted prices applied.
- *   calculated_price:
- *     type: number
- *     description: The calculated price of the variant. Can be a discounted price.
- *   original_price_incl_tax:
- *     type: number
- *     description: The original price of the variant including taxes.
- *   calculated_price_incl_tax:
- *     type: number
- *     description: The calculated price of the variant including taxes.
- *   original_tax:
- *     type: number
- *     description: The taxes applied on the original price.
- *   calculated_tax:
- *     type: number
- *     description: The taxes applied on the calculated price.
- *   tax_rates:
- *     type: array
- *     description: An array of applied tax rates
- *     items:
- *       type: object
- *       properties:
- *         rate:
- *           type: number
- *           description: The tax rate value
- *         name:
- *           type: string
- *           description: The name of the tax rate
- *         code:
- *           type: string
- *           description: The code of the tax rate
- */
diff --git a/packages/medusa/src/types/pricing.ts b/packages/medusa/src/types/pricing.ts
index f3456e397c..43084f06cb 100644
--- a/packages/medusa/src/types/pricing.ts
+++ b/packages/medusa/src/types/pricing.ts
@@ -34,8 +34,63 @@ export type ShippingOptionPricing = {
 export type PricedShippingOption = Partial<ShippingOption> &
   ShippingOptionPricing
 
+/**
+ * @schema PricedVariant
+ * title: "Priced Product Variant"
+ * type: object
+ * allOf:
+ *   - $ref: "#/components/schemas/ProductVariant"
+ *   - type: object
+ *     properties:
+ *       original_price:
+ *         type: number
+ *         description: The original price of the variant without any discounted prices applied.
+ *       calculated_price:
+ *         type: number
+ *         description: The calculated price of the variant. Can be a discounted price.
+ *       original_price_incl_tax:
+ *         type: number
+ *         description: The original price of the variant including taxes.
+ *       calculated_price_incl_tax:
+ *         type: number
+ *         description: The calculated price of the variant including taxes.
+ *       original_tax:
+ *         type: number
+ *         description: The taxes applied on the original price.
+ *       calculated_tax:
+ *         type: number
+ *         description: The taxes applied on the calculated price.
+ *       tax_rates:
+ *         type: array
+ *         description: An array of applied tax rates
+ *         items:
+ *           type: object
+ *           properties:
+ *             rate:
+ *               type: number
+ *               description: The tax rate value
+ *             name:
+ *               type: string
+ *               description: The name of the tax rate
+ *             code:
+ *               type: string
+ *               description: The code of the tax rate
+ */
 export type PricedVariant = Partial<ProductVariant> & ProductVariantPricing
 
+/**
+ * @schema PricedProduct
+ * title: "Priced Product"
+ * type: object
+ * allOf:
+ *   - $ref: "#/components/schemas/Product"
+ *   - type: object
+ *     properties:
+ *       variants:
+ *         type: array
+ *         items:
+ *           $ref: "#/components/schemas/PricedVariant"
+ */
 export type PricedProduct = Omit<Partial<Product>, "variants"> & {
   variants: PricedVariant[]
 }