Rejecting a return with optional message

specification/paths/Returns-v1-returns-return_id-reject.json

@@ -17,6 +17,27 @@
     ],
     "summary": "Reject a return.",
     "description": "This endpoint modifies the status of a return resource to `return-rejected`",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "data": {
+                "type": "object",
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "description": "Message explaining the reason for rejection.",
+                    "example": "The items you've selected are not eligible to be returned because..."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "responses": {
       "204": {
         "description": "The return is rejected."

specification/schemas/hooks/HookActionRejectReturn.json

@@ -6,6 +6,20 @@
       "type": "string",
       "pattern": "^reject-return$",
       "example": "reject-return"
+    },
+    "values": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Message explaining the reason for rejection.",
+            "example": "The items you've selected are not eligible to be returned because..."
+          }
+        }
+      }
     }
   }
 }

specification/schemas/returns/Return.json

@@ -61,6 +61,11 @@
                   "description": "The language that is used for emails for this return. Defaults to the shop's locale."
                 }
               ]
+            },
+            "rejection_message": {
+              "type": "string",
+              "example": "The items you've selected are not eligible to be returned because...",
+              "description": "Message explaining the reason the return was rejected (if at all)."
             }
           }
         },