From f4f27708fb7290a2d398b39b09c9300ee8956b82 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Thu, 17 Sep 2026 08:20:16 +0000
Subject: [PATCH] docs(cards): add substatus and reason to card status change
 examples

Card status changes now require substatus and reason fields. Update the
freezing-and-closing and funding-sources snippets to include these
required fields in curl examples and explain the new requirements.

Syncs with OpenAPI change a0c00c02.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../snippets/cards/freezing-and-closing.mdx   | 23 +++++++++++++++----
 mintlify/snippets/cards/funding-sources.mdx   | 14 +++++++----
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/mintlify/snippets/cards/freezing-and-closing.mdx b/mintlify/snippets/cards/freezing-and-closing.mdx
index 5a13ebabe..81cc51647 100644
--- a/mintlify/snippets/cards/freezing-and-closing.mdx
+++ b/mintlify/snippets/cards/freezing-and-closing.mdx
@@ -14,9 +14,14 @@ funding-source-only flow.
 
 | From | To | Endpoint |
 |------|----|----------|
-| `ACTIVE` | `FROZEN` | `PATCH /cards/{id}` body `{ "status": "FROZEN" }` |
-| `FROZEN` | `ACTIVE` | `PATCH /cards/{id}` body `{ "status": "ACTIVE" }` |
-| `ACTIVE` or `FROZEN` | `CLOSED` | `PATCH /cards/{id}` body `{ "status": "CLOSED" }` |
+| `ACTIVE` | `FROZEN` | `PATCH /cards/{id}` with `status`, `substatus`, and `reason` |
+| `FROZEN` | `ACTIVE` | `PATCH /cards/{id}` with `status`, `substatus`, and `reason` |
+| `ACTIVE` or `FROZEN` | `CLOSED` | `PATCH /cards/{id}` with `status`, `substatus`, and `reason` |
+
+Every status change requires `substatus` (why the card is moving, in the issuer's
+vocabulary) and `reason` (a short sentence explaining the change). See the
+[API reference](/api-reference/cards/update-a-card) for the full list of
+`substatus` values.
 
 Any other transition returns `409 INVALID_STATE_TRANSITION`. In
 particular, you cannot un-freeze a `CLOSED` card — close is terminal.
@@ -29,7 +34,11 @@ in one PATCH — just include both fields in the body.
 curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
   -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
   -H "Content-Type: application/json" \
-  -d '{ "status": "FROZEN" }'
+  -d '{
+    "status": "FROZEN",
+    "substatus": "SUSPICIOUS_ACTIVITY",
+    "reason": "Unrecognised charges reported by the cardholder."
+  }'
 ```
 
 The response is `200 OK` with the updated `Card` and a
@@ -68,7 +77,11 @@ setting `status: "CLOSED"`. The operation is permanent:
 curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
   -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
   -H "Content-Type: application/json" \
-  -d '{ "status": "CLOSED" }'
+  -d '{
+    "status": "CLOSED",
+    "substatus": "END_USER_REQUEST",
+    "reason": "Cardholder asked us to close the card."
+  }'
 ```
 
 `fundingSource` cannot be supplied alongside `status: CLOSED`.
diff --git a/mintlify/snippets/cards/funding-sources.mdx b/mintlify/snippets/cards/funding-sources.mdx
index 625fda0b1..cca202565 100644
--- a/mintlify/snippets/cards/funding-sources.mdx
+++ b/mintlify/snippets/cards/funding-sources.mdx
@@ -62,14 +62,20 @@ from spending, set `status: FROZEN` instead.
 
 ## Stop a card from spending
 
-Freeze the card without changing its funding source:
+Freeze the card without changing its funding source. Every status change
+requires `substatus` and `reason`:
 
 ```bash
 curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
   -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
   -H "Content-Type: application/json" \
-  -d '{ "status": "FROZEN" }'
+  -d '{
+    "status": "FROZEN",
+    "substatus": "SUSPICIOUS_ACTIVITY",
+    "reason": "Unrecognised charges reported by the cardholder."
+  }'
 ```
 
-To permanently retire a card, close it with `PATCH /cards/{id}` and
-`status: "CLOSED"`.
+To permanently retire a card, close it with `PATCH /cards/{id}` supplying
+`status`, `substatus`, and `reason`. See
+[Freezing and closing](/cards/card-management/freezing-and-closing) for details.