From 54b80b7d6c97b74b833d396c4c7ea6883caa9fee Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Fri, 22 May 2026 21:30:19 -0700 Subject: [PATCH] docs(spec): clarify customerType is immutable on PATCH /customers customerType is required on PATCH because it's the discriminator for the oneOf request body, but must match the existing customer's type. The audit found callers accidentally mutating customer type via PATCH. Refs AT-5336 --- mintlify/openapi.yaml | 10 +++++++++- openapi.yaml | 10 +++++++++- .../schemas/customers/CustomerUpdateRequest.yaml | 10 +++++++++- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 6a2a8401..1b084bbf 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -9073,7 +9073,15 @@ components: - customerType properties: customerType: - $ref: '#/components/schemas/CustomerType' + allOf: + - $ref: '#/components/schemas/CustomerType' + description: | + Must equal the existing customer's `customerType`. This field is required + on PATCH because it discriminates the request body shape (INDIVIDUAL vs + BUSINESS); it is not the way to change customer type. Requests that + submit a different `customerType` than the existing record will be + rejected with `INVALID_INPUT`. To change the legal classification of a + customer, create a new customer and migrate its accounts. currencies: type: array items: diff --git a/openapi.yaml b/openapi.yaml index 6a2a8401..1b084bbf 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9073,7 +9073,15 @@ components: - customerType properties: customerType: - $ref: '#/components/schemas/CustomerType' + allOf: + - $ref: '#/components/schemas/CustomerType' + description: | + Must equal the existing customer's `customerType`. This field is required + on PATCH because it discriminates the request body shape (INDIVIDUAL vs + BUSINESS); it is not the way to change customer type. Requests that + submit a different `customerType` than the existing record will be + rejected with `INVALID_INPUT`. To change the legal classification of a + customer, create a new customer and migrate its accounts. currencies: type: array items: diff --git a/openapi/components/schemas/customers/CustomerUpdateRequest.yaml b/openapi/components/schemas/customers/CustomerUpdateRequest.yaml index 15cccec5..a6406296 100644 --- a/openapi/components/schemas/customers/CustomerUpdateRequest.yaml +++ b/openapi/components/schemas/customers/CustomerUpdateRequest.yaml @@ -9,7 +9,15 @@ required: - customerType properties: customerType: - $ref: ./CustomerType.yaml + allOf: + - $ref: ./CustomerType.yaml + description: | + Must equal the existing customer's `customerType`. This field is required + on PATCH because it discriminates the request body shape (INDIVIDUAL vs + BUSINESS); it is not the way to change customer type. Requests that + submit a different `customerType` than the existing record will be + rejected with `INVALID_INPUT`. To change the legal classification of a + customer, create a new customer and migrate its accounts. currencies: type: array items: