feat: document BENEFICIARY_TRUSTED (409) on customer external-account delete

[jklein24]

Summary

DELETE /customers/external-accounts/{externalAccountId} can return 409 when the account is currently a trusted beneficiary, but the spec declared only 204/401/404/500. This documents the missing status and its error code.

• BENEFICIARY_TRUSTED added to the shared Error409 code enum. Because it was absent, a generated client would raise a validation error while deserializing the response instead of surfacing a code the integrator can branch on.
• The delete operation now declares 409 and its description states the ordering requirement: an account that is currently a trusted beneficiary must be untrusted first, via POST /customers/external-accounts/{externalAccountId}/untrust (and its /confirm), before it can be deleted.

Trust cannot be revoked as a side effect of a delete — untrusting a beneficiary requires the customer to complete a Strong Customer Authentication challenge, which a DELETE has no way to carry. So the delete is refused while trust is in place rather than leaving the account deleted but still trusted.

Both changes are additive and non-breaking, so info.version stays 2025-10-13.

Test plan

• make lint exits 0 (Redocly + Spectral, --fail-severity=error): 632 findings, 0 errors, all pre-existing warnings/infos.
• make build rebundled openapi.yaml and mintlify/openapi.yaml; re-running it is a no-op, so the committed bundles byte-match the build output.
• The 409/BENEFICIARY_TRUSTED pair is covered by tests asserting the status and code at the HTTP boundary, alongside the trust → refused-delete → untrust → successful-delete lifecycle.
• Diff is 4 files: 2 spec sources + the 2 generated bundles.

Public

Documents a 409 BENEFICIARY_TRUSTED response on DELETE /customers/external-accounts/{externalAccountId}: an external account that is currently a trusted beneficiary must be untrusted before it can be deleted.

Requested by @jklein24

Original PR: #769

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jul 30, 2026 6:52am
grid-wallet-demo	Ignored	Preview	Jul 30, 2026 6:52am

[akanter]

• feat: document BENEFICIARY_TRUSTED (409) on customer external-account delete #770 👈 (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

docs(api): expand delete usage text for customer external accounts

go

docs(api): clarify delete restrictions for customer external accounts

kotlin

docs(api): clarify deletion constraints for external accounts

openapi

feat(api): add 409 response and BENEFICIARY_TRUSTED enum to external accounts delete

php

docs(api): clarify delete constraint for external accounts

python

docs(api): clarify deletion restrictions in customers external_accounts delete

ruby

docs(api): clarify delete restrictions for external accounts

typescript

docs(api): clarify deletion constraints in external accounts delete method

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

✅ grid-typescript studio · code · diff

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

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

✅ grid-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

✅ grid-ruby studio · code · diff

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

✅ grid-go studio · code · diff

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

go get github.com/stainless-sdks/grid-go@878be2a618383e9815c0c45d9fda90faeaed2c95

✅ grid-kotlin studio · code · diff

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

✅ grid-python studio · code · diff

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

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

✅ grid-php studio · code · diff

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

✅ grid-cli studio · code · diff

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

---

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-07-30 06:57:35 UTC

[ls-bolt]

Your wording change is better than mine — kept it verbatim. The build check was failing because the bundles are generated from openapi/ and hadn't been re-run since the edit, so openapi.yaml and mintlify/openapi.yaml still carried the old sentence.

Pushed the rebundle (make build, 2-line diff in the two generated files). make lint exits 0.

🤖 linked-graphite(#1) | Feedback

[ls-bolt]

Build OpenAPI Documentation and Lint Code & Documentation are both green now after the rebundle. The remaining red check, Mintlify Deployment, is not a spec problem — and I verified that rather than assuming it:

Its log shows the deploy itself succeeding and only the last CDN step failing:

Successfully updated deployment
Navigation updated
Starting page revalidation...
Revalidating 172 paths
Failed to revalidate subdomain: ramps-07-30-feat-document-beneficiary-trusted-409-on-custom

And the preview site is in fact live and serving the new response — BENEFICIARY_TRUSTED appears on the rendered delete endpoint page:

• https://ramps-07-30-feat-document-beneficiary-trusted-409-on-custom.mintlify.site/api-reference/external-accounts/delete-customer-external-account-by-id → 200, contains BENEFICIARY_TRUSTED

So it's a page-revalidation flake on Mintlify's side. It's posted by the Mintlify GitHub app rather than an Actions workflow, so I can't re-run it from here — a push or a nudge from you on their side should clear it. Flagging rather than papering over it in case you'd rather it be green before merging.

🤖 linked-graphite(#1) | Feedback