From 0661d877e8c277ec19fc7cd7f0e38fe91300338c Mon Sep 17 00:00:00 2001 From: Daniel Verner Date: Wed, 18 Feb 2026 12:43:12 +0100 Subject: [PATCH 1/4] Updated schemas to better reflect what needs to be sent/recieved at every point of creating and fetching questions --- .../return-reasons/ShopReturnReason.json | 19 ++++++++++++++++--- .../ShopReturnReasonQuestion.json | 3 --- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/specification/schemas/return-reasons/ShopReturnReason.json b/specification/schemas/return-reasons/ShopReturnReason.json index acb81161..f0f1166d 100644 --- a/specification/schemas/return-reasons/ShopReturnReason.json +++ b/specification/schemas/return-reasons/ShopReturnReason.json @@ -57,18 +57,31 @@ "description": { "type": "string" }, + "is_required": { + "type": "boolean" + }, "answer_type": { "$ref": "#/components/schemas/ReturnQuestionAnswerType" }, - "is_required": { - "type": "boolean" + "yes_note": { + "type": "string", + "maxLength": 255, + "description": "A note to show the user when they answer a `boolean` type question with `true`. Will be shown in the return portal." + }, + "no_note": { + "type": "string", + "maxLength": 255, + "description": "A note to show the user when they answer a `boolean` type question with `false`. Will be shown in the return portal." } }, "example": [ { "code": "what-size", "description": "What size would you like instead?", - "is_required": true + "is_required": true, + "answer_type": "boolean", + "yes_note": "This product can't be returned after its been used. Proceeding will lead to a rejected return request.", + "no_note": "This product cannot be returned after it was unsealed. Proceeding will lead to a rejected return request." } ] } diff --git a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json index 50a57923..48c478ed 100644 --- a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json +++ b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json @@ -16,9 +16,6 @@ "description": "Indication whether a consumer is required to answer this question related to the selected return reason", "example": true }, - "answer_type": { - "$ref": "#/components/schemas/ReturnQuestionAnswerType" - }, "yes_note": { "type": "string", "maxLength": 255, From 1ec6f74504fb3623fb6b164e56b905d77d12b3ab Mon Sep 17 00:00:00 2001 From: Nick de Vries Date: Wed, 18 Feb 2026 13:31:54 +0100 Subject: [PATCH 2/4] :recycle: Refactored ShopReturnReason related schemas to remove duplication --- .../return-reasons/ShopReturnReason.json | 41 +------------------ .../ShopReturnReasonQuestion.json | 8 ++++ .../ShopReturnReasonResponse.json | 12 +++++- 3 files changed, 20 insertions(+), 41 deletions(-) diff --git a/specification/schemas/return-reasons/ShopReturnReason.json b/specification/schemas/return-reasons/ShopReturnReason.json index f0f1166d..4e7e8b0f 100644 --- a/specification/schemas/return-reasons/ShopReturnReason.json +++ b/specification/schemas/return-reasons/ShopReturnReason.json @@ -44,46 +44,7 @@ "questions": { "type": "array", "items": { - "required": [ - "code", - "description", - "answer_type", - "is_required" - ], - "properties": { - "code": { - "type": "string" - }, - "description": { - "type": "string" - }, - "is_required": { - "type": "boolean" - }, - "answer_type": { - "$ref": "#/components/schemas/ReturnQuestionAnswerType" - }, - "yes_note": { - "type": "string", - "maxLength": 255, - "description": "A note to show the user when they answer a `boolean` type question with `true`. Will be shown in the return portal." - }, - "no_note": { - "type": "string", - "maxLength": 255, - "description": "A note to show the user when they answer a `boolean` type question with `false`. Will be shown in the return portal." - } - }, - "example": [ - { - "code": "what-size", - "description": "What size would you like instead?", - "is_required": true, - "answer_type": "boolean", - "yes_note": "This product can't be returned after its been used. Proceeding will lead to a rejected return request.", - "no_note": "This product cannot be returned after it was unsealed. Proceeding will lead to a rejected return request." - } - ] + "$ref": "#/components/schemas/ShopReturnReasonQuestion" } } } diff --git a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json index 48c478ed..131d6a9e 100644 --- a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json +++ b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json @@ -11,11 +11,19 @@ "description": "The code of the shop return question", "example": "what-size" }, + "description": { + "type": "string", + "readOnly": true + }, "is_required": { "type": "boolean", "description": "Indication whether a consumer is required to answer this question related to the selected return reason", "example": true }, + "answer_type": { + "$ref": "#/components/schemas/ReturnQuestionAnswerType", + "readOnly": true + }, "yes_note": { "type": "string", "maxLength": 255, diff --git a/specification/schemas/return-reasons/ShopReturnReasonResponse.json b/specification/schemas/return-reasons/ShopReturnReasonResponse.json index 90b046e3..8fa517de 100644 --- a/specification/schemas/return-reasons/ShopReturnReasonResponse.json +++ b/specification/schemas/return-reasons/ShopReturnReasonResponse.json @@ -18,7 +18,17 @@ "requires_attachments", "accepts_comment", "requires_comment" - ] + ], + "properties": { + "questions": { + "items": { + "required": [ + "answer_type", + "description" + ] + } + } + } }, "links": { "readOnly": true, From cfe08251353b9397ae3a35e410a5c35c37698740 Mon Sep 17 00:00:00 2001 From: Daniel Verner Date: Wed, 18 Feb 2026 14:08:29 +0100 Subject: [PATCH 3/4] better examples --- .../return-questions/ReturnQuestionAnswerType.json | 1 - .../schemas/return-reasons/ShopReturnReasonQuestion.json | 9 ++++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/specification/schemas/return-questions/ReturnQuestionAnswerType.json b/specification/schemas/return-questions/ReturnQuestionAnswerType.json index 0f5b044e..178db1a8 100644 --- a/specification/schemas/return-questions/ReturnQuestionAnswerType.json +++ b/specification/schemas/return-questions/ReturnQuestionAnswerType.json @@ -4,6 +4,5 @@ "string", "boolean" ], - "example": "string", "description": "The type of answer expected for this question." } diff --git a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json index 131d6a9e..c730bd7f 100644 --- a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json +++ b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json @@ -9,11 +9,13 @@ "code": { "type": "string", "description": "The code of the shop return question", - "example": "what-size" + "example": "was-the-item-used" }, "description": { "type": "string", - "readOnly": true + "readOnly": true, + "description": "The description of the shop return question. This is shown to the consumer in the return portal when they select a return reason with this question attached.", + "example": "Was the item used?" }, "is_required": { "type": "boolean", @@ -22,7 +24,8 @@ }, "answer_type": { "$ref": "#/components/schemas/ReturnQuestionAnswerType", - "readOnly": true + "readOnly": true, + "example": "boolean" }, "yes_note": { "type": "string", From edcc24be5b65db32e11696bae4aeb910a66c9ad0 Mon Sep 17 00:00:00 2001 From: Daniel Verner Date: Wed, 18 Feb 2026 14:27:35 +0100 Subject: [PATCH 4/4] better examples --- .../return-orders/ItemReasonQuestion.json | 2 +- .../CreateReturnQuestionRequest.json | 4 ++-- .../PatchReturnQuestionRequest.json | 2 +- .../return-questions/ReturnQuestion.json | 8 ++++---- .../return-reasons/ShopReturnReason.json | 18 +++++++++++++++++- .../ShopReturnReasonQuestion.json | 8 ++++---- .../schemas/returns/GetReturnItem.json | 4 ++-- 7 files changed, 31 insertions(+), 15 deletions(-) diff --git a/specification/schemas/return-orders/ItemReasonQuestion.json b/specification/schemas/return-orders/ItemReasonQuestion.json index 63fe94b9..62881244 100644 --- a/specification/schemas/return-orders/ItemReasonQuestion.json +++ b/specification/schemas/return-orders/ItemReasonQuestion.json @@ -7,7 +7,7 @@ "properties": { "code": { "type": "string", - "example": "what-size", + "example": "product-used", "description": "A code that identifies the question for the return of this item. See the return-question `code` attribute." }, "answer": { diff --git a/specification/schemas/return-questions/CreateReturnQuestionRequest.json b/specification/schemas/return-questions/CreateReturnQuestionRequest.json index 5c1629bc..2ac7821e 100644 --- a/specification/schemas/return-questions/CreateReturnQuestionRequest.json +++ b/specification/schemas/return-questions/CreateReturnQuestionRequest.json @@ -11,7 +11,7 @@ "properties": { "code": { "type": "string", - "example": "wrong-item", + "example": "product-used", "description": "A unique code for the return question." }, "description": { @@ -21,7 +21,7 @@ }, { "example": { - "en-GB": "What size would you like in return?" + "en-GB": "Has the product been used or worn?" } } ] diff --git a/specification/schemas/return-questions/PatchReturnQuestionRequest.json b/specification/schemas/return-questions/PatchReturnQuestionRequest.json index 2ed7025b..35aedc2c 100644 --- a/specification/schemas/return-questions/PatchReturnQuestionRequest.json +++ b/specification/schemas/return-questions/PatchReturnQuestionRequest.json @@ -16,7 +16,7 @@ }, { "example": { - "en-GB": "What size would you like in return?" + "en-GB": "Has the product been used or worn?" } } ] diff --git a/specification/schemas/return-questions/ReturnQuestion.json b/specification/schemas/return-questions/ReturnQuestion.json index 813242bf..6911dec0 100644 --- a/specification/schemas/return-questions/ReturnQuestion.json +++ b/specification/schemas/return-questions/ReturnQuestion.json @@ -15,15 +15,15 @@ "code": { "type": "string", "maxLength": 255, - "example": "what-size", - "description": "What size would you like in return?" + "example": "product-used", + "description": "A unique code for the return question." }, "description": { "oneOf": [ { "type": "string", "description": "A localized return question description", - "example": "What size would you like in return?" + "example": "Has the product been used or worn?" }, { "allOf": [ @@ -32,7 +32,7 @@ }, { "example": { - "en-GB": "What size would you like in return?" + "en-GB": "Has the product been used or worn?" } } ] diff --git a/specification/schemas/return-reasons/ShopReturnReason.json b/specification/schemas/return-reasons/ShopReturnReason.json index 4e7e8b0f..23f31891 100644 --- a/specification/schemas/return-reasons/ShopReturnReason.json +++ b/specification/schemas/return-reasons/ShopReturnReason.json @@ -45,7 +45,23 @@ "type": "array", "items": { "$ref": "#/components/schemas/ShopReturnReasonQuestion" - } + }, + "example": [ + { + "code": "product-used", + "description": "Has the product been used or worn?", + "is_required": true, + "answer_type": "boolean", + "yes_note": "Used products may not be eligible for a full refund.", + "no_note": "Thank you for confirming the product is unused." + }, + { + "code": "preferred-size", + "description": "What size would you like instead?", + "is_required": false, + "answer_type": "string" + } + ] } } } diff --git a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json index c730bd7f..55f2004f 100644 --- a/specification/schemas/return-reasons/ShopReturnReasonQuestion.json +++ b/specification/schemas/return-reasons/ShopReturnReasonQuestion.json @@ -9,13 +9,13 @@ "code": { "type": "string", "description": "The code of the shop return question", - "example": "was-the-item-used" + "example": "product-condition" }, "description": { "type": "string", "readOnly": true, "description": "The description of the shop return question. This is shown to the consumer in the return portal when they select a return reason with this question attached.", - "example": "Was the item used?" + "example": "Is the product still in its original packaging?" }, "is_required": { "type": "boolean", @@ -31,13 +31,13 @@ "type": "string", "maxLength": 255, "description": "A note to show the user when they answer a `boolean` type question with `true`. Will be shown in the return portal.", - "example": "This product can't be returned after its been used. Proceeding will lead to a rejected return request." + "example": "Great! Please ensure all tags and packaging materials are included." }, "no_note": { "type": "string", "maxLength": 255, "description": "A note to show the user when they answer a `boolean` type question with `false`. Will be shown in the return portal.", - "example": "This product cannot be returned after it was unsealed. Proceeding will lead to a rejected return request." + "example": "Products must be returned in original packaging. Proceeding may lead to a rejected return request." } } } diff --git a/specification/schemas/returns/GetReturnItem.json b/specification/schemas/returns/GetReturnItem.json index 22a052af..ffc2d4d6 100644 --- a/specification/schemas/returns/GetReturnItem.json +++ b/specification/schemas/returns/GetReturnItem.json @@ -137,7 +137,7 @@ { "type": "string", "description": "A localized return question description", - "example": "What size would you like in return?" + "example": "Has the product been used or worn?" }, { "allOf": [ @@ -146,7 +146,7 @@ }, { "example": { - "en-GB": "What size would you like in return?" + "en-GB": "Has the product been used or worn?" } } ]