Bol · Schema

Return

E-CommerceRetailMarketplaceNetherlands

Properties

Name Type Description
returnId string Unique identifier for a return.
registrationDateTime string The date and time in ISO 8601 format when this return was registered.
fulfilmentMethod string The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
returnItems array
View JSON Schema on GitHub

JSON Schema

bol-com-return-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bol-com/json-schema/bol-com-return-schema.json",
  "title": "Return",
  "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/Return",
  "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/ReturnItem"
      }
    }
  },
  "$defs": {
    "CustomerDetails": {
      "required": [
        "salutation"
      ],
      "type": "object",
      "properties": {
        "salutation": {
          "type": "string",
          "description": "The salutation of the customer.",
          "enum": [
            "MALE",
            "FEMALE",
            "UNKNOWN"
          ]
        },
        "firstName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The first name of the customer."
        },
        "surname": {
          "type": [
            "string",
            "null"
          ],
          "description": "The surname of the customer."
        },
        "streetName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The street name."
        },
        "houseNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The house number."
        },
        "houseNumberExtension": {
          "type": [
            "string",
            "null"
          ],
          "description": "The extension on the house number."
        },
        "extraAddressInformation": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional information related to the address that helps in delivering the package."
        },
        "zipCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "The ZIP code in '1234AB' format for NL orders and '0000' format for BE orders."
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of the city."
        },
        "countryCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "The country code."
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "A scrambled email address that can be used to contact the customer."
        },
        "deliveryPhoneNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The delivery phone number of the customer. Filled in case the order requires an appointment for delivering the goods."
        },
        "company": {
          "type": [
            "string",
            "null"
          ],
          "description": "The company name."
        },
        "vatNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Value Added Tax (VAT) / BTW number for business sellers situated in the Netherlands."
        }
      },
      "description": "Information related to the customer."
    },
    "ReturnItem": {
      "required": [
        "customerDetails",
        "ean",
        "expectedQuantity",
        "handled",
        "orderId",
        "processingResults",
        "returnReason",
        "rmaId",
        "title"
      ],
      "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."
        },
        "title": {
          "type": "string",
          "description": "The product title."
        },
        "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"
        },
        "trackAndTrace": {
          "type": [
            "string",
            "null"
          ],
          "description": "The track and trace code that is associated with this transport."
        },
        "transporterName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of the transporter."
        },
        "handled": {
          "type": "boolean",
          "description": "Indicates if this return item has been handled (by the retailer)."
        },
        "processingResults": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ReturnProcessingResult"
          }
        },
        "customerDetails": {
          "allOf": [
            {
              "$ref": "#/$defs/CustomerDetails"
            }
          ]
        }
      }
    },
    "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"
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/bol-com-return"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.