Add required totalBalance field to InternalAccount

[wuvictor-95]

Summary

Adds a new totalBalance field to the Grid internal account schema, alongside the existing balance:

• balance — the balance available to spend, excluding pending and held funds
• totalBalance — the total balance, including pending and held funds

totalBalance is marked required in the response. Both fields now carry descriptions distinguishing them. Spec rebundled (openapi.yaml + mintlify/openapi.yaml).

Rollout note

This marks totalBalance as a required response field in the public contract. The Grid API server (webdev) should be deployed returning total_balance before this spec change is published, so external clients regenerating from the spec never expect a field the server isn't yet returning. Server-side wiring is in the companion webdev PR.

🤖 Generated with Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jun 15, 2026 9:13pm

[github-actions]

⚠️ Breaking OpenAPI changes detected

This PR introduces breaking changes to openapi.yaml:

API Changelog 2025-10-13 vs. 2025-10-13

API Changes

POST webhook:internal-account-status

• ⚠️ added the new required request property allOf[subschema #2]/data/totalBalance

---

Detected by oasdiff. This PR will need approval from an API reviewer before merge.

[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

feat(api): add total_balance field to internal account response

go

feat(api): add TotalBalance field to InternalAccount and webhook events

kotlin

feat(api): add totalBalance field to InternalAccount model

openapi

feat(api): add totalBalance field to InternalAccount

php

feat(api): add totalBalance field to InternalAccount model

python

feat(api): add total_balance field to sandbox InternalAccount

ruby

feat(api): add total_balance field to InternalAccount model

typescript

feat(api): add totalBalance field to internal account responses

✅ grid-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ grid-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⏳ grid-go studio · code

generate ✅ → build ✅ → lint ⏳ → test ❗

go get github.com/stainless-sdks/grid-go@a4ab65509a98b76da65bef8a8781e8e466fdca19

⚠️ grid-kotlin studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ❗

✅ grid-typescript studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/1e47f85bdae0e87997f97922115a517bcc243e0b/dist.tar.gz

⚠️ grid-python studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/27ccf1f9e68bf3cd5c3c97e83e63b4728359d202/grid-0.0.1-py3-none-any.whl

⚠️ grid-csharp studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ✅ → test ❗

✅ grid-php studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️ grid-cli studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → 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-06-15 21:35:04 UTC

[greptile-apps]

Greptile Summary

(つ≧▽≦)つ✨ ~*~ cute review time ~*~ ✨(=^･ω･^=)

This PR adds totalBalance as a required field to the InternalAccount schema, distinguishing it from the existing balance field (available-to-spend only) by including pending and held funds. The spec is correctly edited in the openapi/ source directory and rebundled into both openapi.yaml and mintlify/openapi.yaml.

• Schema update (InternalAccount.yaml): totalBalance added to the required array and as a new property; descriptions added to both balance and totalBalance using the OpenAPI 3.1-valid $ref + sibling description pattern.
• Example updates: totalBalance added to the PATCH endpoint and both webhook payload examples; the balanceDecrease webhook example correctly shows differing values (balance: 10000, totalBalance: 12500) illustrating the field semantics.
• GbpBeneficiary: example values added to each field — a clean bundled-in documentation improvement with no issues.

Confidence Score: 5/5

Safe to merge — the change is an additive, backward-compatible spec extension and the rollout note correctly calls out that the server should be deployed before this spec is published.

The change is purely additive: a new required field is added to the response schema, the source YAML files are the only things edited, and the bundles are correctly regenerated. No existing fields are modified or removed, and all inline examples maintain the invariant that totalBalance >= balance.

No files require special attention. The only stylistic note is that the PATCH response example uses equal values for balance and totalBalance, which misses an opportunity to illustrate the field distinction but has no runtime impact.

Important Files Changed

Filename	Overview
openapi/components/schemas/customers/InternalAccount.yaml	Adds totalBalance to the required array and as a new property (with $ref + sibling description, valid in OpenAPI 3.1); also adds a description to the existing balance field.
openapi/paths/internal_accounts/internal_accounts_{id}.yaml	Adds totalBalance to the PATCH 200 response example; balance and totalBalance values are identical (12550) which misses an opportunity to illustrate their distinction.
openapi/webhooks/internal-account-status.yaml	Adds totalBalance to both webhook examples; balanceDecrease correctly shows balance: 10000 vs totalBalance: 12500, illustrating the semantic difference.
openapi/components/schemas/common/GbpBeneficiary.yaml	Adds example values to each field — a bundled-together documentation improvement, no issues.
openapi.yaml	Generated bundle — correctly reflects all source changes after make build.
mintlify/openapi.yaml	Generated Mintlify bundle — correctly reflects all source changes after make build.

Entity Relationship Diagram

%%{init: {'theme': 'neutral'}}%%
erDiagram
    InternalAccount {
        string id
        string customerId
        string type
        string status
        CurrencyAmount balance "available to spend (excl. pending/held)"
        CurrencyAmount totalBalance "total incl. pending and held funds [NEW - required]"
        array fundingPaymentInstructions
        boolean privateEnabled
        datetime createdAt
        datetime updatedAt
    }
    CurrencyAmount {
        integer amount
        Currency currency
    }
    Currency {
        string code
        string name
        string symbol
        integer decimals
    }
    InternalAccount ||--|| CurrencyAmount : balance
    InternalAccount ||--|| CurrencyAmount : totalBalance
    CurrencyAmount ||--|| Currency : currency

Loading

_{Reviews (2): Last reviewed commit: "Fix lint: add totalBalance to InternalAc..." | Re-trigger Greptile}