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

⚠️ grid-openapi studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️

✅ grid-ruby studio · code

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

⚠️ grid-go 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 ❗

go get github.com/stainless-sdks/grid-go@9b036e8276bdf80524f8dd25c15acfa99025692c

⚠️ 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-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/63d309cafd9dee3bdd61ad0b94c6c7516632ed0b/grid-0.0.1-py3-none-any.whl

✅ grid-typescript studio · conflict

Your SDK build had at least one note diagnostic.

✅ 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 build CI job, which is a regression from the base state.
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 20:18:59 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

[greptile-apps]

Greptile Summary

       .       .
    .  |  /|  .
     \ | / | /
  ----\|/--|/----
      /|\  /|\
     /_|_\/_|_\
       /  \
  ☠ RIFFS OF THE TRUSTED BENEFICIARY ☠

UNTRUST, CONFIRM, DELETE — THEN LET THE 409 SILENCE BREAK.

• Documents the 409 BENEFICIARY_TRUSTED response for customer external-account deletion.
• Adds BENEFICIARY_TRUSTED to the shared Error409 code enum and description table.
• Explains the required untrust and confirmation flow before deletion.
• Regenerates both committed OpenAPI bundles from the modular source.

Confidence Score: 5/5

The PR appears safe to merge with the source specification and both generated bundles consistently documenting the existing conflict response.

The new response references the established shared Error409 schema, the error code is present in both its enum and documentation table, the prescribed untrust/confirm endpoints match the existing API flow, and both generated bundles remain synchronized.

Important Files Changed

Filename	Overview
openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml	Adds the documented 409 response and accurate untrust/confirm remediation for deleting a trusted beneficiary.
openapi/components/schemas/errors/Error409.yaml	Adds BENEFICIARY_TRUSTED consistently to the shared 409 enum and its documentation table.
openapi.yaml	Correctly reflects the source path and Error409 schema changes in the generated root bundle.
mintlify/openapi.yaml	Remains synchronized with the generated root OpenAPI bundle for local Mintlify rendering.

_{Reviews (1): Last reviewed commit: "Rebundle openapi.yaml after the descript..." | Re-trigger Greptile}

[ls-bolt]

📌 Bolt Status

2026-07-30 16:18:30 UTC — ⚡ Agent linked-graphite-2(#2) started

---

Feedback

[ls-bolt]

Status after the approval, since the checks still show one red: this is merge-ready.

• mergeStateStatus is UNSTABLE, not BLOCKED — so the one failing check is not a required one.

• Build OpenAPI Documentation, Lint Code & Documentation, Detect breaking changes, and preview all pass on 5702a3d.

• The only red is Mintlify Deployment, and it's a stale status rather than a real failure. Its log ends with Successfully updated deployment / Navigation updated and then fails on the final CDN step (Failed to revalidate subdomain: ramps-07-30-…). I just re-confirmed the published page serves the change correctly:

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

I tried to re-request that check run directly and got a 403 — it's owned by the Mintlify app, so ls-bolt can't retrigger it. I deliberately did not push an empty commit to shake it loose, since that would invalidate shreyav's approval for a cosmetic status.

One sequencing note: this spec PR should land before webdev #31456 (the implementation), so the documented 409 is published no later than the behavior that returns it.

🤖 linked-graphite(#2) | Feedback