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 consolidates customer-related OpenAPI schemas by extracting inline definitions into reusable components (CreateCustomerRequest and UpdateCustomerRequest). The refactoring improves maintainability but introduces a critical breaking change.

Key Changes

• Created dedicated CreateCustomerRequest and UpdateCustomerRequest schema components that use discriminators to route between IndividualCustomerUpdate and BusinessCustomerUpdate
• Changed enum: [INDIVIDUAL] to const: INDIVIDUAL in IndividualCustomerUpdate.yaml for better OpenAPI semantics
• Added platformCustomerId field to IndividualCustomerUpdate.yaml (now available in both create and update operations)
• Moved kycStatus/kybStatus from base Customer.yaml to specific customer type schemas (IndividualCustomer and BusinessCustomer)
• Removed platformCustomerId and umaAddress from required fields in base Customer.yaml
• Removed inline examples from path files (were: individualCustomerWithUmaAddress, individualCustomerWithoutUmaAddress, businessCustomer)
• Renamed KycStatus.yaml to KycKybStatus.yaml

Critical Issue

The previous CREATE endpoint used allOf with explicit required: [platformCustomerId] to enforce this field during creation. The new CreateCustomerRequest schema references IndividualCustomerUpdate.yaml which does not mark platformCustomerId as required. This makes platformCustomerId optional for creation when it was previously mandatory - a breaking change that could cause API validation issues.

Additional Concerns

• The kycUrl response field was removed from the CREATE endpoint schema
• All request examples were removed, reducing API documentation quality

Confidence Score: 2/5

• This PR contains a breaking change that makes a previously required field optional
• The refactoring successfully consolidates schemas and improves maintainability, but introduces a critical breaking change where platformCustomerId is no longer enforced as required during customer creation. The old schema explicitly required this field via allOf constraints, but the new schema doesn't enforce this requirement.
• CreateCustomerRequest.yaml and IndividualCustomerUpdate.yaml need attention to restore the required platformCustomerId constraint for creation operations

Important Files Changed

Filename	Overview
openapi/components/schemas/customers/CreateCustomerRequest.yaml	New schema that's identical to UpdateCustomerRequest but doesn't enforce platformCustomerId as required (breaking change from previous inline schema)
openapi/components/schemas/customers/IndividualCustomerUpdate.yaml	Changed enum: [INDIVIDUAL] to const: INDIVIDUAL and added platformCustomerId field (now available in both create and update)
openapi/components/schemas/customers/Customer.yaml	Removed platformCustomerId and umaAddress from required fields, moved kycStatus to specific customer type schemas
openapi/paths/customers/customers.yaml	Replaced inline schema with CreateCustomerRequest ref, removed all examples and kycUrl field from previous schema
openapi.yaml	Bundled OpenAPI spec reflecting all customer schema changes (breaking change: platformCustomerId no longer required for creation)
mintlify/openapi.yaml	Copy of bundled OpenAPI spec for Mintlify docs (identical changes to openapi.yaml)

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Grid API
    participant DB as Database
    
    Note over Client,DB: Create Customer Flow
    Client->>API: POST /customers<br/>(CreateCustomerRequest)
    Note over API: Validates customerType discriminator<br/>(INDIVIDUAL or BUSINESS)
    API->>API: Route to IndividualCustomerUpdate<br/>or BusinessCustomerUpdate schema
    API->>DB: Create customer record
    DB-->>API: Customer created
    API-->>Client: 201 Created<br/>(Customer response with kycStatus/kybStatus)
    
    Note over Client,DB: Update Customer Flow
    Client->>API: PATCH /customers/{customerId}<br/>(UpdateCustomerRequest)
    Note over API: Validates customerType discriminator<br/>(INDIVIDUAL or BUSINESS)
    API->>API: Route to IndividualCustomerUpdate<br/>or BusinessCustomerUpdate schema
    API->>DB: Update customer record
    DB-->>API: Customer updated
    API-->>Client: 200 OK<br/>(Customer response with kycStatus/kybStatus)

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.