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.