feat: add Customer API discriminators and consolidate customer changes

[pengying]

TL;DR

Refactored OpenAPI schema definitions for customer-related endpoints to improve maintainability and consistency.

What changed?

• Created dedicated schema components for CreateCustomerRequest and UpdateCustomerRequest
• Moved inline schema definitions from API paths to reusable component schemas
• Changed enum: [INDIVIDUAL] to const: INDIVIDUAL in the IndividualCustomerUpdate schema for better semantics
• Added platformCustomerId directly to the IndividualCustomerUpdate schema
• Removed redundant examples from the API paths as they're now defined in the schema components

[pengying]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: add Stainless SDK config and misc cleanups #132
• feat: rename Error to GridError and add additionalProperties to error schemas #131
• feat: add Customer API discriminators and consolidate customer changes #130 👈 (View in Graphite)
• feat: add Quote/Transaction discriminators and remove inline examples #129
• feat: add isPlatformAccount to PaymentInstructions and remove PaymentAccountOrWalletInfo refs #128
• feat: rename accounts to data in list external accounts response #127
• feat: convert single-value enums to const for base types #126
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR refactors customer-related OpenAPI schemas by extracting inline definitions into reusable components (CreateCustomerRequest and UpdateCustomerRequest), improving maintainability. However, the refactoring introduces a breaking change: platformCustomerId was explicitly required in the old CREATE endpoint but is now optional in the new schema structure.

Key Changes

• Created CreateCustomerRequest.yaml and UpdateCustomerRequest.yaml wrapper schemas with discriminators
• Added platformCustomerId to IndividualCustomerUpdate.yaml (now available in UPDATE operations)
• Changed enum: [INDIVIDUAL] to const: INDIVIDUAL for better semantics
• Removed kycUrl field from CREATE request body
• Removed inline examples from API path files

Issues Found

• Breaking Change: platformCustomerId went from required to optional in CREATE requests, creating a mismatch with the Customer.yaml response schema which requires this field
• CreateCustomerRequest and UpdateCustomerRequest are identical schemas - no differentiation between create and update requirements
• platformCustomerId is now updateable (wasn't before) - verify this is intentional

Confidence Score: 2/5

• This PR contains a breaking API change that will affect existing integrations
• Score reflects critical breaking change where required field became optional, plus semantic concerns about Create/Update schemas being identical when they should enforce different constraints
• Pay close attention to openapi/components/schemas/customers/CreateCustomerRequest.yaml and openapi/components/schemas/customers/IndividualCustomerUpdate.yaml - these need platformCustomerId constraint fixes

Important Files Changed

Filename	Overview
openapi/components/schemas/customers/CreateCustomerRequest.yaml	New wrapper schema for customer creation that references IndividualCustomerUpdate/BusinessCustomerUpdate with discriminator, but doesn't enforce platformCustomerId as required (breaking change)
openapi/components/schemas/customers/IndividualCustomerUpdate.yaml	Changed enum to const for customerType, added platformCustomerId field (now available in UPDATE operations when it wasn't before)
openapi/paths/customers/customers.yaml	Replaced inline schema with CreateCustomerRequest reference, removed kycUrl field from request and all inline examples

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant Schema as CreateCustomerRequest
    participant Discriminator
    participant Individual as IndividualCustomerUpdate
    participant Business as BusinessCustomerUpdate
    
    Note over Client,Business: Customer Creation Flow
    
    Client->>API: POST /customers
    API->>Schema: Validate request body
    Schema->>Discriminator: Check customerType field
    
    alt customerType: INDIVIDUAL
        Discriminator->>Individual: Route to IndividualCustomerUpdate
        Note over Individual: ❌ platformCustomerId optional<br/>(was required in old schema)
        Individual-->>Schema: Validation result
    else customerType: BUSINESS
        Discriminator->>Business: Route to BusinessCustomerUpdate
        Business-->>Schema: Validation result
    end
    
    Schema-->>API: Request validated
    API-->>Client: 201 Customer created
    Note over API,Client: Response includes required<br/>platformCustomerId per Customer.yaml

Loading

[greptile-apps]

_{4 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

openapi/components/schemas/customers/BusinessCustomerUpdate.yaml
Missing platformCustomerId field. The previous CREATE endpoint required this for business customers via allOf. Either add it to this schema (like IndividualCustomerUpdate.yaml) or handle it differently in CreateCustomerRequest.yaml.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/customers/BusinessCustomerUpdate.yaml
Line: 1:33

Comment:
Missing `platformCustomerId` field. The previous CREATE endpoint required this for business customers via `allOf`. Either add it to this schema (like `IndividualCustomerUpdate.yaml`) or handle it differently in `CreateCustomerRequest.yaml`.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

CreateCustomerRequest and UpdateCustomerRequest are completely identical. The old CREATE endpoint required platformCustomerId via allOf constraints, but this new schema doesn't enforce that requirement. This is a breaking change that makes platformCustomerId optional for creation when it was previously required.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/customers/CreateCustomerRequest.yaml
Line: 1:18

Comment:
`CreateCustomerRequest` and `UpdateCustomerRequest` are completely identical. The old CREATE endpoint required `platformCustomerId` via `allOf` constraints, but this new schema doesn't enforce that requirement. This is a breaking change that makes `platformCustomerId` optional for creation when it was previously required.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Check that removing the kycUrl response field from the CREATE endpoint won't break existing API consumers expecting this field in responses.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers.yaml
Line: 15:15

Comment:
Check that removing the `kycUrl` response field from the CREATE endpoint won't break existing API consumers expecting this field in responses.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

openapi/components/schemas/customers/BusinessCustomerUpdate.yaml
Check that BusinessCustomerUpdate intentionally lacks platformCustomerId field while IndividualCustomerUpdate now has it - creates inconsistency between customer types

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/customers/BusinessCustomerUpdate.yaml
Line: 1:13

Comment:
Check that `BusinessCustomerUpdate` intentionally lacks `platformCustomerId` field while `IndividualCustomerUpdate` now has it - creates inconsistency between customer types

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

This schema references IndividualCustomerUpdate.yaml which doesn't mark platformCustomerId as required. The old CREATE endpoint explicitly required this field via allOf constraints. Since Customer.yaml response schema requires platformCustomerId, the API likely expects this field during creation. This mismatch between request schema (optional) and what the API actually requires (mandatory) will cause validation confusion.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/customers/CreateCustomerRequest.yaml
Line: 1:18

Comment:
This schema references `IndividualCustomerUpdate.yaml` which doesn't mark `platformCustomerId` as required. The old CREATE endpoint explicitly required this field via `allOf` constraints. Since `Customer.yaml` response schema requires `platformCustomerId`, the API likely expects this field during creation. This mismatch between request schema (optional) and what the API actually requires (mandatory) will cause validation confusion.

How can I resolve this? If you propose a fix, please make it concise.