{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bol-com/json-schema/bol-com-returns-response-schema.json",
  "title": "ReturnsResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bol-com-returns-api-openapi.yml#/components/schemas/ReturnsResponse",
  "required": [
    "returns"
  ],
  "type": "object",
  "properties": {
    "returns": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ReducedReturn"
      }
    }
  },
  "$defs": {
    "ReducedReturn": {
      "required": [
        "fulfilmentMethod",
        "registrationDateTime",
        "returnId",
        "returnItems"
      ],
      "type": "object",
      "properties": {
        "returnId": {
          "type": "string",
          "description": "Unique identifier for a return."
        },
        "registrationDateTime": {
          "type": "string",
          "description": "The date and time in ISO 8601 format when this return was registered.",
          "format": "date-time"
        },
        "fulfilmentMethod": {
          "type": "string",
          "description": "The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB)."
        },
        "returnItems": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ReducedReturnItem"
          }
        }
      }
    },
    "ReducedReturnItem": {
      "required": [
        "ean",
        "expectedQuantity",
        "handled",
        "orderId",
        "processingResults",
        "returnReason",
        "rmaId"
      ],
      "type": "object",
      "properties": {
        "rmaId": {
          "type": "string",
          "description": "The RMA (Return Merchandise Authorization) identifier of the return."
        },
        "orderId": {
          "type": "string",
          "description": "The id of the customer order this return item is in."
        },
        "ean": {
          "type": "string",
          "description": "The EAN number associated with this product."
        },
        "expectedQuantity": {
          "type": "integer",
          "description": "The quantity that is expected to be returned by the customer. Note: this can be greater than 1 in case the customer ordered a quantity greater than 1 of the same product in the same customer order.",
          "format": "int32"
        },
        "returnReason": {
          "$ref": "#/$defs/ReturnReason"
        },
        "handled": {
          "type": "boolean",
          "description": "Indicates if this return item has been handled (by the retailer)."
        },
        "processingResults": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ReturnProcessingResult"
          }
        }
      }
    },
    "ReturnProcessingResult": {
      "required": [
        "handlingResult",
        "processingDateTime",
        "processingResult",
        "quantity"
      ],
      "type": "object",
      "properties": {
        "quantity": {
          "type": "integer",
          "description": "The processed quantity.",
          "format": "int32"
        },
        "processingResult": {
          "type": "string",
          "description": "The processing result of the return."
        },
        "handlingResult": {
          "type": "string",
          "description": "The handling result requested by the retailer."
        },
        "processingDateTime": {
          "type": "string",
          "description": "The date and time in ISO 8601 format when the return was processed.",
          "format": "date-time"
        }
      }
    },
    "ReturnReason": {
      "required": [
        "customerComments",
        "mainReason"
      ],
      "type": "object",
      "properties": {
        "mainReason": {
          "type": "string",
          "description": "The main reason describing why the customer returned this product."
        },
        "detailedReason": {
          "type": [
            "string",
            "null"
          ],
          "description": "The sub reason describing why the customer returned this product in more detail."
        },
        "customerComments": {
          "type": "string",
          "description": "Additional details from the customer as to why this item was returned."
        }
      },
      "description": "\nThe reason why the customer returned this product.\n\n- **mainReason** (required): The main reason describing why the customer returned this product.\n  Allowed values (examples): `Verkeerde maat of afmeting`, `Verkeerd besteld`\n\n- **detailedReason**: The sub reason describing why the customer returned this product in more detail.\n  Allowed values **depend on mainReason**:\n\n| mainReason                          | detailedReason values                                                                                                                                                                                 | comments                                                                                       |\n|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |------------------------------------------------------------------------------------------------|\n| Verkeerde maat of afmeting          | Te groot, Te klein, Artikel werkt niet op mijn apparatuur, Meerdere maten/afmetingen besteld, Aanbevolen accessoire past niet, Meerdere opties/artikelen besteld, Pasvorm valt tegen, Anders-namelijk | Optional customer text input                                                                   |\n| Verkeerd besteld                    | Onduidelijke productinformatie, Onduidelijke afbeelding, Dubbel besteld, Artikel had ik toch niet nodig, Aanbevolen accessoire past niet, Anders-namelijk                                             | Optional customer text input                                                                   |\n| Artikel werkt niet                  | -                                                                                                                                                                                                     | Optional customer text input                                                                   |\n| Klacht over artikel                 | Artikel is beschadigd, Artikel werkt niet, Artikel is incompleet, Kwaliteit valt tegen, Gebruiksaanwijzing onduidelijk, Artikel doet niet wat het belooft, Anders-namelijk                            | `customerComments` is mandatory only when \"Artikel werkt niet\" is selected. Otherwise Optional |\n| Klacht over de bezorging            | Artikel is te laat bezorgd, Verpakking is beschadigd, Artikel is beschadigd, Ander artikel ontvangen dan besteld, Anders-namelijk                                                                     | Optional customer text input                                                                   |\n| Elders goedkoper                    | -                                                                                                                                                                                                     | Optional customer text input                                                                   |\n| Ander artikel ontvangen dan besteld | Onduidelijke productinformatie, Onduidelijke afbeelding, Ander artikel ontvangen dan besteld                                                                                                          | Optional customer text input                                                                   |\n| Anders                              | Artikel cadeau ontvangen, Ik heb me bedacht, Artikel had ik toch niet nodig, Kwaliteit valt tegen, Andere kleur dan gedacht, Meerdere opties/artikelen besteld, Dubbel besteld, Anders-namelijk       | Optional customer text input                                                                   |\n|                                     |                                                                                                                                                                                                       |                                                                                                |\n- **customerComments** (required): Additional details from the customer about the return. Could be empty\n"
    }
  }
}