docs(cards): drop the never-emitted REFUNDED card transaction status - #903
docs(cards): drop the never-emitted REFUNDED card transaction status#903AaryamanBhute wants to merge 2 commits into
Conversation
Grid stopped deriving REFUNDED for card transactions in webdev#30710 (2026-07-20): a merchant return leaves the transaction SETTLED and reports the returned value in refundedAmount. The server enum, the status derivation, and the webhook type mapper have not carried REFUNDED since, so the published CardTransactionStatus value, the CARD_TRANSACTION.REFUNDED webhook type, and the sandbox return / return-reversal descriptions documented a transition that never fires. Remove the value and the webhook type, reword the return simulators and the card docs snippets around refundedAmount, and turn the webhook example for a returned purchase into a SETTLED delivery. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EvF4PtTuGgETX8vFnsYEjQ
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
github-actions
Bot
added
the
breaking-change
|
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
|
Greptile SummaryThis PR aligns the public card documentation and OpenAPI schemas with the implemented return behavior:
Confidence Score: 4/5The PR should not merge until the breaking enum removals are released under a new matching API version and server path; the return-reversal result should also be clarified. The documentation consistently reflects same-status returns, but removing two published enum members changes generated SDK contracts while retaining the existing API version, violating the repository's breaking-change versioning requirement. Files Needing Attention: openapi/components/schemas/cards/CardTransactionStatus.yaml, openapi/components/schemas/webhooks/WebhookType.yaml, openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/cards/CardTransactionStatus.yaml | Removes a published enum member and documents returns as preserving SETTLED, but does so without the required API version transition. |
| openapi/components/schemas/webhooks/WebhookType.yaml | Removes the public CARD_TRANSACTION.REFUNDED webhook enum member, contributing to the unversioned generated-client contract change. |
| openapi/webhooks/card-transaction.yaml | Consistently updates webhook prose and examples to use CARD_TRANSACTION.SETTLED with refundedAmount. |
| openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml | Corrects the reversal precondition but leaves the resulting effect on refundedAmount undocumented. |
| mintlify/snippets/cards/reconciliation.mdx | Updates the card lifecycle diagram and status table consistently with same-status returns. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart LR
A[AUTHORIZED] --> P[PARTIALLY_SETTLED]
A --> S[SETTLED]
P --> S
P --> E[EXCEPTION]
S -->|Merchant return| S
S -. updated refundedAmount .-> W[CARD_TRANSACTION.SETTLED webhook]
Prompt To Fix All With AI
### Issue 1
openapi/components/schemas/cards/CardTransactionStatus.yaml:3-6
**Unversioned breaking enum removal**
Removing `REFUNDED` and `CARD_TRANSACTION.REFUNDED` changes the public enum types generated for SDKs. Existing consumers that reference either member will fail when they regenerate or upgrade. The repository requires breaking changes to bump `info.version` and use a matching new `servers.url`, but both remain on `2025-10-13`. This version transition must be made before merging. The same issue applies to the removals in `WebhookType.yaml` and `CardTransactionWebhook.yaml`.
### Issue 2
openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml:3-8
**Reversal result remains unclear**
The revised description makes a non-zero `refundedAmount` the return-reversal precondition, but it does not explain how a successful reversal changes that field. Without saying whether the amount decreases or returns to zero, sandbox users cannot reliably assert the resulting transaction state and may treat it as an irreversible cumulative total.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(cards): drop the never-emitted REFU..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
A successful reversal is netted off refundedAmount (a full reversal brings it back to 0) and the status stays SETTLED, matching the server's returns-minus-reversals derivation. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EvF4PtTuGgETX8vFnsYEjQ
1 participant
Reason
Grid stopped deriving
REFUNDEDfor card transactions in lightsparkdev/webdev#30710 (2026-07-20). A merchant return leaves the transactionSETTLEDand reports the returned value inrefundedAmount; the server enum, the status derivation, and the webhook type mapper have not carriedREFUNDEDsince. That PR noted the spec change belonged here and left it undone, so the publishedCardTransactionStatusvalue, theCARD_TRANSACTION.REFUNDEDwebhook type, and the sandbox return / return-reversal descriptions have documented a transition that never fires.No integrator ever received it: card transaction webhooks only started firing on 2026-08-11, and the only production card traffic postdates the change.
Overview
CardTransactionStatus: removeREFUNDED; theSETTLEDrow now says a return does not change the status and shows up inrefundedAmount.WebhookTypeandCardTransactionWebhook: removeCARD_TRANSACTION.REFUNDED. The webhook description and its "returned by the merchant" example now describe aCARD_TRANSACTION.SETTLEDdelivery.SandboxCardReturnRequest: reworded aroundrefundedAmount. Return reversal requires a non-zerorefundedAmount, which is what the server checks.No
info.versionbump: nothing observable changes, the value was never emitted.Webdev side (dead enum member, dashboard leftover): lightsparkdev/webdev#34465.
Test plan
make buildandnpm run lint:openapi(Redocly + Spectral) pass with no new findings.🤖 Generated with Claude Code
https://claude.ai/code/session_01EvF4PtTuGgETX8vFnsYEjQ