From fbea8018de980767e1f30a656366d32cf07d06a2 Mon Sep 17 00:00:00 2001
From: Mark Slowey <mark.slowey1@nhs.net>
Date: Tue, 18 Aug 2026 13:41:53 +0100
Subject: [PATCH 1/3] clarify reason status usage

---
 .../api/components/documentation/patchLetter.md      | 12 ++++++++++--
 .../api/components/documentation/postLetters.md      | 10 ++++++++--
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md
index e29b229d5..2eb45db69 100644
--- a/specification/api/components/documentation/patchLetter.md
+++ b/specification/api/components/documentation/patchLetter.md
@@ -23,11 +23,19 @@ Allowed `status` values that can be used to are:
 
 It is not possible to update a letter to status of `PENDING`.
 
+### Reason Codes
+
 Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body.
 
-### Example Error Codes
+With the exception of the `RETURNED` status, `reasonCode` and `reasonText` can be agreed on an individual basis
+
+#### RETURNED Updates
+
+NHS Notify uses a standardised set of reasons for the `RETURNED` status.
+
+Both a `reasonCode` and `reasonText` <b>must</b> be provided for a `RETURNED` status update.
 
-Examples of reason codes and text that may be returned include (but are not limited to)
+The reason codes and expected text for the `RETURNED` status are as follows:
 
 | Reason Code | Reason Text                |
 |-------------|----------------------------|
diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md
index e1b2b1273..298e68f96 100644
--- a/specification/api/components/documentation/postLetters.md
+++ b/specification/api/components/documentation/postLetters.md
@@ -29,9 +29,15 @@ The request should not contain multiple letter objects with the same ID.
 
 Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update.
 
-### Example Error Codes
+With the exception of the `RETURNED` status, `reasonCode` and `reasonText` can be agreed on an individual basis based on supplier workflows.
 
-Examples of reason codes and text that may be returned include (but are not limited to)
+#### RETURNED Updates
+
+NHS Notify uses a standardised set of reasons for the `RETURNED` status.
+
+Both a `reasonCode` and `reasonText` <b>must</b> be provided for a `RETURNED` status update.
+
+The reason codes and expected text for the `RETURNED` status are as follows:
 
 | Reason Code | Reason Text                |
 |-------------|----------------------------|

From 022c82b20af3830bd4e6da6acc8d42e405d3cc2f Mon Sep 17 00:00:00 2001
From: Mark Slowey <mark.slowey1@nhs.net>
Date: Tue, 18 Aug 2026 13:44:18 +0100
Subject: [PATCH 2/3] version bump

---
 VERSION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/VERSION b/VERSION
index 6a1200d76..0aec44bc0 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.3.0-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}
+1.3.1-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}

From 723ef1b76cc59dbaa44933cf73443ed6e4e0811c Mon Sep 17 00:00:00 2001
From: Mark Slowey <mark.slowey1@nhs.net>
Date: Tue, 18 Aug 2026 13:50:26 +0100
Subject: [PATCH 3/3] disable top lvl header as sub config not being picked up

---
 .markdownlint.jsonc              | 3 ++-
 specification/.markdownlint.json | 6 ------
 2 files changed, 2 insertions(+), 7 deletions(-)
 delete mode 100644 specification/.markdownlint.json

diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
index a2672f790..93ec2c05f 100644
--- a/.markdownlint.jsonc
+++ b/.markdownlint.jsonc
@@ -7,5 +7,6 @@
     "siblings_only": true
   },
   // https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
-  "MD033": false
+  "MD033": false,
+  "MD041": false
 }
diff --git a/specification/.markdownlint.json b/specification/.markdownlint.json
deleted file mode 100644
index d4221b279..000000000
--- a/specification/.markdownlint.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
-  "MD041": {
-    "level": 2
-  },
-  "extends": "../.markdownlint.jsonc"
-}