diff --git a/.changeset/olive-seas-repair.md b/.changeset/olive-seas-repair.md
new file mode 100644
index 0000000000..243515304d
--- /dev/null
+++ b/.changeset/olive-seas-repair.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+feat(oas): add @schema OAS for address request payloads
diff --git a/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts b/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts
index 1db19ef899..9d9300f0b5 100644
--- a/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts
+++ b/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts
@@ -181,12 +181,12 @@ enum Status {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   shipping_address:
  *     description: "The Address to be used for shipping."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   items:
  *     description: The Line Items that have been received.
diff --git a/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts b/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts
index 8a699d58a3..d8c1ba3c59 100644
--- a/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts
+++ b/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts
@@ -160,12 +160,12 @@ export default async (req, res) => {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   shipping_address:
  *     description: "The Address to be used for shipping."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *       - type: string
  *   discounts:
  *     description: "An array of Discount codes to add to the Draft Order."
diff --git a/packages/medusa/src/api/routes/admin/orders/__tests__/create-claim.js b/packages/medusa/src/api/routes/admin/orders/__tests__/create-claim.js
index e592b2f722..b2c0662abb 100644
--- a/packages/medusa/src/api/routes/admin/orders/__tests__/create-claim.js
+++ b/packages/medusa/src/api/routes/admin/orders/__tests__/create-claim.js
@@ -2,7 +2,7 @@ import { IdMap } from "medusa-test-utils"
 import { request } from "../../../../../helpers/test-request"
 import { ClaimServiceMock } from "../../../../../services/__mocks__/claim"
 
-describe("POST /admin/order/:id/claims", () => {
+describe("POST /admin/orders/:id/claims", () => {
   describe("successfully creates a claim", () => {
     let subject
 
diff --git a/packages/medusa/src/api/routes/admin/orders/create-claim.ts b/packages/medusa/src/api/routes/admin/orders/create-claim.ts
index 8a6a0a848b..18cde2177a 100644
--- a/packages/medusa/src/api/routes/admin/orders/create-claim.ts
+++ b/packages/medusa/src/api/routes/admin/orders/create-claim.ts
@@ -18,7 +18,7 @@ import { ClaimTypeValue } from "../../../../types/claim"
 import { AddressPayload, FindParams } from "../../../../types/common"
 
 /**
- * @oas [post] /admin/order/{id}/claims
+ * @oas [post] /admin/orders/{id}/claims
  * operationId: "PostOrdersOrderClaims"
  * summary: "Create a Claim"
  * description: "Creates a Claim."
@@ -383,9 +383,8 @@ export default async (req, res) => {
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
  *   shipping_address:
- *      type: object
  *      description: "An optional shipping address to send the claim to. Defaults to the parent order's shipping address"
- *      $ref: "#/components/schemas/Address"
+ *      $ref: "#/components/schemas/AddressPayload"
  *   refund_amount:
  *      description: The amount to refund the Customer when the Claim type is `refund`.
  *      type: integer
diff --git a/packages/medusa/src/api/routes/admin/orders/create-swap.ts b/packages/medusa/src/api/routes/admin/orders/create-swap.ts
index bff5dede11..4fe82cdaa6 100644
--- a/packages/medusa/src/api/routes/admin/orders/create-swap.ts
+++ b/packages/medusa/src/api/routes/admin/orders/create-swap.ts
@@ -23,7 +23,7 @@ import { Type } from "class-transformer"
 import { FindParams } from "../../../../types/common"
 
 /**
- * @oas [post] /admin/order/{id}/swaps
+ * @oas [post] /admin/orders/{id}/swaps
  * operationId: "PostOrdersOrderSwaps"
  * summary: "Create a Swap"
  * description: "Creates a Swap. Swaps are used to handle Return of previously purchased goods and Fulfillment of replacements simultaneously."
diff --git a/packages/medusa/src/api/routes/admin/orders/update-claim.ts b/packages/medusa/src/api/routes/admin/orders/update-claim.ts
index 78e20e945a..fe357b8a6e 100644
--- a/packages/medusa/src/api/routes/admin/orders/update-claim.ts
+++ b/packages/medusa/src/api/routes/admin/orders/update-claim.ts
@@ -16,7 +16,7 @@ import { validator } from "../../../../utils/validator"
 import { FindParams } from "../../../../types/common"
 
 /**
- * @oas [post] /admin/order/{id}/claims/{claim_id}
+ * @oas [post] /admin/orders/{id}/claims/{claim_id}
  * operationId: "PostOrdersOrderClaimsClaim"
  * summary: "Update a Claim"
  * description: "Updates a Claim."
diff --git a/packages/medusa/src/api/routes/admin/orders/update-order.ts b/packages/medusa/src/api/routes/admin/orders/update-order.ts
index 9c972a4c83..c509451cc2 100644
--- a/packages/medusa/src/api/routes/admin/orders/update-order.ts
+++ b/packages/medusa/src/api/routes/admin/orders/update-order.ts
@@ -108,12 +108,10 @@ export default async (req, res) => {
  *     type: string
  *   billing_address:
  *     description: Billing address
- *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *     $ref: "#/components/schemas/AddressPayload"
  *   shipping_address:
  *     description: Shipping address
- *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *     $ref: "#/components/schemas/AddressPayload"
  *   items:
  *     description: The Line Items for the order
  *     type: array
diff --git a/packages/medusa/src/api/routes/store/carts/update-cart.ts b/packages/medusa/src/api/routes/store/carts/update-cart.ts
index 7434f7f6e0..af9aaab19e 100644
--- a/packages/medusa/src/api/routes/store/carts/update-cart.ts
+++ b/packages/medusa/src/api/routes/store/carts/update-cart.ts
@@ -136,14 +136,14 @@ class Discount {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/Address"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *         description: A full billing address object.
  *       - type: string
  *         description: The billing address ID
  *   shipping_address:
  *     description: "The Address to be used for shipping."
  *     anyOf:
- *       - $ref: "#/components/schemas/Address"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *         description: A full shipping address object.
  *       - type: string
  *         description: The shipping address ID
diff --git a/packages/medusa/src/api/routes/store/customers/create-address.ts b/packages/medusa/src/api/routes/store/customers/create-address.ts
index b3e871e368..bfe2f4e587 100644
--- a/packages/medusa/src/api/routes/store/customers/create-address.ts
+++ b/packages/medusa/src/api/routes/store/customers/create-address.ts
@@ -117,16 +117,7 @@ export default async (req, res) => {
  * properties:
  *   address:
  *     description: "The Address to add to the Customer."
- *     allOf:
- *       - $ref: "#/components/schemas/AddressFields"
- *       - type: object
- *         required:
- *           - first_name
- *           - last_name
- *           - address_1
- *           - city
- *           - country_code
- *           - postal_code
+ *     $ref: "#/components/schemas/AddressCreatePayload"
  */
 export class StorePostCustomersCustomerAddressesReq {
   @ValidateNested()
diff --git a/packages/medusa/src/api/routes/store/customers/update-address.ts b/packages/medusa/src/api/routes/store/customers/update-address.ts
index aa2563b3ff..b1b45db1db 100644
--- a/packages/medusa/src/api/routes/store/customers/update-address.ts
+++ b/packages/medusa/src/api/routes/store/customers/update-address.ts
@@ -98,7 +98,7 @@ export default async (req, res) => {
 /**
  * @schema StorePostCustomersCustomerAddressesAddressReq
  * anyOf:
- *   - $ref: "#/components/schemas/AddressFields"
+ *   - $ref: "#/components/schemas/AddressPayload"
  */
 // eslint-disable-next-line max-len
 export class StorePostCustomersCustomerAddressesAddressReq extends AddressPayload {}
diff --git a/packages/medusa/src/api/routes/store/customers/update-customer.ts b/packages/medusa/src/api/routes/store/customers/update-customer.ts
index 2227efb94b..86a0304cf1 100644
--- a/packages/medusa/src/api/routes/store/customers/update-customer.ts
+++ b/packages/medusa/src/api/routes/store/customers/update-customer.ts
@@ -100,7 +100,7 @@ export default async (req, res) => {
  *   billing_address:
  *     description: "The Address to be used for billing purposes."
  *     anyOf:
- *       - $ref: "#/components/schemas/AddressFields"
+ *       - $ref: "#/components/schemas/AddressPayload"
  *         description: The full billing address object
  *       - type: string
  *         description: The ID of an existing billing address
diff --git a/packages/medusa/src/models/address.ts b/packages/medusa/src/models/address.ts
index 333fd2e510..f32bbc47ad 100644
--- a/packages/medusa/src/models/address.ts
+++ b/packages/medusa/src/models/address.ts
@@ -66,61 +66,6 @@ export class Address extends SoftDeletableEntity {
   }
 }
 
-/**
- * @schema AddressFields
- * title: "Address Fields"
- * description: "Address fields used when creating/updating an address."
- * type: object
- * properties:
- *  company:
- *    type: string
- *    description: Company name
- *    example: Acme
- *  first_name:
- *    type: string
- *    description: First name
- *    example: Arno
- *  last_name:
- *    type: string
- *    description: Last name
- *    example: Willms
- *  address_1:
- *    type: string
- *    description: Address line 1
- *    example: 14433 Kemmer Court
- *  address_2:
- *    type: string
- *    description: Address line 2
- *    example: Suite 369
- *  city:
- *    type: string
- *    description: City
- *    example: South Geoffreyview
- *  country_code:
- *    type: string
- *    description: The 2 character ISO code of the country in lower case
- *    externalDocs:
- *      url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
- *      description: See a list of codes.
- *    example: st
- *  province:
- *    type: string
- *    description: Province
- *    example: Kentucky
- *  postal_code:
- *    type: string
- *    description: Postal Code
- *    example: 72093
- *  phone:
- *    type: string
- *    description: Phone Number
- *    example: 16128234334802
- *  metadata:
- *    type: object
- *    description: An optional key-value map with additional details
- *    example: {car: "white"}
- */
-
 /**
  * @schema Address
  * title: "Address"
diff --git a/packages/medusa/src/types/common.ts b/packages/medusa/src/types/common.ts
index 7a10b4d55d..275ad0a7eb 100644
--- a/packages/medusa/src/types/common.ts
+++ b/packages/medusa/src/types/common.ts
@@ -186,6 +186,57 @@ export class NumericalComparisonOperator {
   lte?: number
 }
 
+/**
+ * @schema AddressPayload
+ * type: object
+ * description: "Address fields used when creating/updating an address."
+ * properties:
+ *   first_name:
+ *     description: First name
+ *     type: string
+ *     example: Arno
+ *   last_name:
+ *     description: Last name
+ *     type: string
+ *     example: Willms
+ *   phone:
+ *     type: string
+ *     description: Phone Number
+ *     example: 16128234334802
+ *   company:
+ *     type: string
+ *   address_1:
+ *     description: Address line 1
+ *     type: string
+ *     example: 14433 Kemmer Court
+ *   address_2:
+ *     description: Address line 2
+ *     type: string
+ *     example: Suite 369
+ *   city:
+ *     description: City
+ *     type: string
+ *     example: South Geoffreyview
+ *   country_code:
+ *     description: The 2 character ISO code of the country in lower case
+ *     type: string
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *       description: See a list of codes.
+ *     example: st
+ *   province:
+ *     description: Province
+ *     type: string
+ *     example: Kentucky
+ *   postal_code:
+ *     description: Postal Code
+ *     type: string
+ *     example: 72093
+ *   metadata:
+ *     type: object
+ *     example: {car: "white"}
+ *     description: An optional key-value map with additional details
+ */
 export class AddressPayload {
   @IsOptional()
   @IsString()
@@ -232,6 +283,64 @@ export class AddressPayload {
   postal_code?: string
 }
 
+/**
+ * @schema AddressCreatePayload
+ * type: object
+ * description: "Address fields used when creating an address."
+ * required:
+ *   - first_name
+ *   - last_name
+ *   - address_1
+ *   - city
+ *   - country_code
+ *   - postal_code
+ * properties:
+ *   first_name:
+ *     description: First name
+ *     type: string
+ *     example: Arno
+ *   last_name:
+ *     description: Last name
+ *     type: string
+ *     example: Willms
+ *   phone:
+ *     type: string
+ *     description: Phone Number
+ *     example: 16128234334802
+ *   company:
+ *     type: string
+ *   address_1:
+ *     description: Address line 1
+ *     type: string
+ *     example: 14433 Kemmer Court
+ *   address_2:
+ *     description: Address line 2
+ *     type: string
+ *     example: Suite 369
+ *   city:
+ *     description: City
+ *     type: string
+ *     example: South Geoffreyview
+ *   country_code:
+ *     description: The 2 character ISO code of the country in lower case
+ *     type: string
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *       description: See a list of codes.
+ *     example: st
+ *   province:
+ *     description: Province
+ *     type: string
+ *     example: Kentucky
+ *   postal_code:
+ *     description: Postal Code
+ *     type: string
+ *     example: 72093
+ *   metadata:
+ *     type: object
+ *     example: {car: "white"}
+ *     description: An optional key-value map with additional details
+ */
 export class AddressCreatePayload {
   @IsString()
   first_name: string