docs(transactions): document the cancel 501 and add a CANCELED transaction status

[ls-bolt]

Summary

POST /transactions/{transactionId}/cancel shipped without three things integrators need:

• The 501 was undocumented. It is the response for every rail whose banking partner exposes no cancellation facility — the endpoint's most common path, not an edge case — so integrators hit an undocumented status.
• There was no way to see that a cancel succeeded. OutgoingTransactionStatus had no CANCELED, so a confirmed cancellation was indistinguishable from a payment that failed on our side.
• The description promised wire cancellation, which never works. A wire leg is not cancellable and always returns 409.

Changes: 7 files

• openapi/paths/transactions/transactions_{transactionId}_cancel.yaml
  • Add the 501 response (Error501, already used by /cards, /customers, /platform/config).
  • Rewrite the 200 description: a success means the partner accepted the request, not that the transfer is already cancelled — it confirms asynchronously, so the returned transaction may still report its pre-cancellation status.
  • Scope the description to ACH. Wires and RTP cannot be withdrawn once submitted and are never cancellable; the old text offered wire cancellation that the API refuses with a 409.
• openapi/components/schemas/transactions/OutgoingTransactionStatus.yaml — add the terminal CANCELED status.
• openapi/components/schemas/webhooks/WebhookType.yaml, OutgoingPaymentWebhook.yaml — add OUTGOING_PAYMENT.CANCELED. Without it a cancelled transfer has no webhook type to send under, so a webhook-enabled platform would only learn of the cancellation by polling.
• mintlify/changelog.mdx — August 2026 entry for the endpoint. The API's own 501 message tells integrators to "track availability in the Grid changelog", which until now never mentioned it.
• openapi.yaml, mintlify/openapi.yaml — regenerated bundles (make build).

No info.version bump — additive only.

Verification

• make build regenerates cleanly.
• make lint-openapi exits 0; remaining output is the pre-existing example/description info+warning noise on *Beneficiary schemas.

Notes

• Supersedes the unreviewed draft docs(transactions): document the 501 response on the cancel endpoint #774, whose 200/501 wording is preserved verbatim here; that branch also carried a duplicated commit, so this is rebuilt on current main. Close docs(transactions): document the 501 response on the cancel endpoint #774 in favour of this.
• CANCELED is spec-only until the backend emits it — that lands in a follow-up on webdev, which maps a cancellation-driven flow-run failure to this status instead of folding it into FAILED. Ordering is deliberate: the spec accepts the value before anything produces it.

Requested by @aaryaman

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 24, 2026, 11:51 PM

[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	Aug 25, 2026 11:55pm
grid-wallet-demo	Ignored	Preview	Aug 25, 2026 11:55pm

[lightspark-bot]

• docs(transactions): document the cancel 501 and add a CANCELED transaction status #862 👈 (View in Graphite)
• main

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