docs(spec): clarify customerType is immutable on PATCH /customers

[jklein24]

Summary

Adds a description to the customerType property on the customer-update
request schemas clarifying that this field is the request-body
discriminator and must equal the existing customer's type. Type changes
require a new customer.

Why

The error audit (parent epic AT-5324) found callers can submit a
different customerType on PATCH than the existing customer's, silently
converting INDIVIDUAL → BUSINESS (or vice versa) and losing required
fields. The server-side rejection fix is tracked under the same ticket;
this PR tightens the spec so the contract is unambiguous.

Test plan

• make build clean
• make lint clean
• Reviewer to confirm the rendered docs show the new description on the
  customer-update schemas.

Refs AT-5336

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 23, 2026 4:31am

[jklein24]

• docs(spec): clarify customerType is immutable on PATCH /customers #497 👈 (View in Graphite)
• main

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

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

csharp

chore(internal): regenerate SDK with no functional changes

go

chore(internal): regenerate SDK with no functional changes

kotlin

chore(internal): regenerate SDK with no functional changes

openapi

docs(api): document customerType parameter in customer update

php

chore(internal): regenerate SDK with no functional changes

python

chore(internal): regenerate SDK with no functional changes

ruby

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-cli studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ❗ → lint ❗ → test ❗

✅ grid-openapi studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗

✅ grid-ruby studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ✅) → lint ❗ → test ✅

✅ grid-go studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ✅) → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@3b20c1f40c677e61bb7877aadfa435ed54f59325

✅ grid-python studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ✅

⏳ grid-csharp studio · code · diff

generate ❗ → build ⏭️ (prev: build ❗) → lint ⏭️ (prev: lint ❗) → test ⏳

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ❗

✅ grid-typescript studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ❗) → lint ⏭️ (prev: lint ❗) → test ❗

✅ grid-php studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → lint ❗ → test ✅

⏳ These are partial results; builds are still running.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-23 04:34:26 UTC

[greptile-apps]

Greptile Summary

This PR adds a clarifying description to the customerType field in CustomerUpdateRequest across the source schema and both generated bundles. The description explains that customerType is required on PATCH only as a discriminator and must match the existing customer's type — it cannot be used to mutate the type.

• openapi/components/schemas/customers/CustomerUpdateRequest.yaml is the authoritative source edit; openapi.yaml and mintlify/openapi.yaml reflect the expected output of make build.
• The allOf: [$ref] + sibling description pattern is the correct OpenAPI 3.x idiom for annotating a $ref without overriding it.

Confidence Score: 5/5

Documentation-only clarification with no behavioural or schema changes — safe to merge.

All three files change only the description on an existing required field; the allOf wrapping is the standard OpenAPI 3.x idiom and does not alter validation semantics. The source file was edited in the canonical location and the two generated bundles reflect a consistent make build output.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/components/schemas/customers/CustomerUpdateRequest.yaml	Source schema edit — adds immutability description to customerType using the correct allOf+$ref pattern.
openapi.yaml	Generated bundle updated consistently with the source schema change; diff matches expected make build output.
mintlify/openapi.yaml	Mintlify-targeted generated bundle; identical change as root openapi.yaml, consistent with bundler output.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as PATCH /customers/{id}
    participant DB

    Client->>API: "PATCH { customerType: INDIVIDUAL, ... }"
    API->>DB: Fetch existing customer
    DB-->>API: "Customer { customerType: INDIVIDUAL }"
    API->>API: customerType matches? ✓
    API->>DB: Apply update (non-type fields only)
    DB-->>API: Updated customer
    API-->>Client: 200 OK

    Note over Client,API: If submitted customerType ≠ existing type
    Client->>API: "PATCH { customerType: BUSINESS, ... }"
    API->>DB: Fetch existing customer
    DB-->>API: "Customer { customerType: INDIVIDUAL }"
    API->>API: customerType matches? ✗
    API-->>Client: 400 INVALID_INPUT

Loading

_{Reviews (1): Last reviewed commit: "docs(spec): clarify customerType is immu..." | Re-trigger Greptile}

[jklein24]

Closing — the underlying defects (filed under epic AT-5324) are server-side runtime issues that need to be fixed in sparkcore, not here in the spec. These spec-level clarifications can be reopened as follow-ups once the server fixes land if still useful.