v10 - Returns - Demo Endpoints

Create return for order item 1044796550

Create a return and handle it immediately for order item 1044796550.

POST /retailer-demo/returns

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: application/vnd.retailer.v10+json
Authorization: Bearer token (omitted)

{
  "orderItemId" : 1044796550,
  "quantityReturned" : 1,
  "handlingResult" : "RETURN_RECEIVED"
}

Content-Type: application/vnd.retailer.v10+json

Status: 202 ACCEPTED

{
  "processStatusId" : "1",
  "eventType" : "CREATE_RETURN_ITEM",
  "description" : "Create return for order item 1044796550.",
  "status" : "PENDING",
  "createTimestamp" : "2025-07-09T14:08:04+02:00",
  "links" : [ {
    "rel" : "self",
    "href" : "http://api.bol.com/shared-demo/process-status/1",
    "method" : "GET"
  } ]
}

Handle return for order item 6107434013

Handle the return for order item 6107434013 with rmaId 86123452.

PUT /retailer-demo/returns/86123452

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: application/vnd.retailer.v10+json
Authorization: Bearer token (omitted)

{
  "handlingResult" : "RETURN_RECEIVED",
  "quantityReturned" : 3
}

Content-Type: application/vnd.retailer.v10+json

Status: 202 ACCEPTED

{
  "processStatusId" : "1",
  "entityId" : "86123452",
  "eventType" : "HANDLE_RETURN_ITEM",
  "description" : "Handle the return item with rma id 86123452.",
  "status" : "PENDING",
  "createTimestamp" : "2025-07-09T14:08:04+02:00",
  "links" : [ {
    "rel" : "self",
    "href" : "http://api.bol.com/shared-demo/process-status/1",
    "method" : "GET"
  } ]
}

Handle return for order item 6107331383

Handle the return for order item 6107434013 with rmaId 86129741.

PUT /retailer-demo/returns/86129741

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: application/vnd.retailer.v10+json
Authorization: Bearer token (omitted)

{
  "handlingResult" : "EXCHANGE_PRODUCT",
  "quantityReturned" : 1
}

Content-Type: application/vnd.retailer.v10+json

Status: 202 ACCEPTED

{
  "processStatusId" : "1",
  "entityId" : "86129741",
  "eventType" : "HANDLE_RETURN_ITEM",
  "description" : "Handle the return item with rma id 86129741.",
  "status" : "PENDING",
  "createTimestamp" : "2025-07-09T14:08:04+02:00",
  "links" : [ {
    "rel" : "self",
    "href" : "http://api.bol.com/shared-demo/process-status/1",
    "method" : "GET"
  } ]
}

Handle return for order item 6107432387

Handle the return for order item 6107434013 with rmaId 86126399.

PUT /retailer-demo/returns/86224896

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: application/vnd.retailer.v10+json
Authorization: Bearer token (omitted)

{
  "handlingResult" : "RETURN_RECEIVED",
  "quantityReturned" : 3
}

Content-Type: application/vnd.retailer.v10+json

Status: 202 ACCEPTED

{
  "processStatusId" : "1",
  "entityId" : "86224896",
  "eventType" : "HANDLE_RETURN_ITEM",
  "description" : "Handle the return item with rma id 86224896.",
  "status" : "PENDING",
  "createTimestamp" : "2025-07-09T14:08:04+02:00",
  "links" : [ {
    "rel" : "self",
    "href" : "http://api.bol.com/shared-demo/process-status/1",
    "method" : "GET"
  } ]
}

Get a multi-item return where both returns are handled

Retrieve a FBR multi-item return for order 1043965710 and 1044194100 that is registered by the customer.

GET /retailer-demo/returns/15896813

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returnId" : "15896813",
  "registrationDateTime" : "2019-05-09T13:04:22+02:00",
  "fulfilmentMethod" : "FBR",
  "returnItems" : [ {
    "rmaId" : "60282945",
    "orderId" : "1044194100",
    "ean" : "3138520283072",
    "title" : "Campingaz Cv470 Plus - Easy clic",
    "expectedQuantity" : 1,
    "returnReason" : {
      "mainReason" : "Artikel is defect/werkt niet",
      "customerComments" : "Andere verwachting"
    },
    "trackAndTrace" : "3SBLCR954606709",
    "transporterName" : "PostNL",
    "handled" : true,
    "processingResults" : [ {
      "quantity" : 1,
      "processingResult" : "CANCELLED",
      "handlingResult" : "EXPIRED",
      "processingDateTime" : "2019-05-30T13:06:03+02:00"
    } ],
    "customerDetails" : {
      "salutation" : "MALE",
      "firstName" : "Luke",
      "surname" : "Skywalker",
      "streetName" : "Acmestraat",
      "houseNumber" : "1",
      "zipCode" : "1234AB",
      "city" : "Acme City",
      "countryCode" : "NL",
      "email" : "2wb3y4vqq667avck657zbhx2uevm7a@verkopen.test2.bol.com",
      "company" : "Company Corp"
    }
  }, {
    "rmaId" : "60282944",
    "orderId" : "1043965710",
    "ean" : "0811571016532",
    "title" : "Google Chromecast 2",
    "expectedQuantity" : 1,
    "returnReason" : {
      "mainReason" : "Verkeerd artikel ontvangen"
    },
    "trackAndTrace" : "12ABCD345678900",
    "transporterName" : "PostNL",
    "handled" : true,
    "processingResults" : [ {
      "quantity" : 1,
      "processingResult" : "ACCEPTED",
      "handlingResult" : "RETURN_RECEIVED",
      "processingDateTime" : "2019-05-09T13:05:09+02:00"
    } ],
    "customerDetails" : {
      "salutation" : "UNKNOWN",
      "zipCode" : "1234AB",
      "countryCode" : "NL",
      "email" : "2wb3y4vqq667avck657zbhx2uevm7a@verkopen.test2.bol.com"
    }
  } ]
}

Get all unhandled returns for FBB orders

Retrieves all open returns that were 'Fulfillment by bol.com', which are sorted by date in descending order. Note that the track and trace information is only returned when available.

GET /retailer-demo/returns?fulfilment-method=FBB&handled=false

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returns" : [ {
    "returnId" : "6",
    "registrationDateTime" : "2018-04-27T19:55:12+02:00",
    "fulfilmentMethod" : "FBB",
    "returnItems" : [ {
      "rmaId" : "86127131",
      "orderId" : "7616247328",
      "ean" : "8718526069334",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Verkeerd besteld",
        "customerComments" : "Ik wilde eigenlijk een groter formaat"
      },
      "handled" : false
    } ]
  } ]
}

Get all unhandled returns

Retrieves all open returns, which are sorted by date in descending order. Note that track and trace information and delivery phone number elements are only returned when available.

GET /retailer-demo/returns?handled=false

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returns" : [ {
    "returnId" : "15897410",
    "registrationDateTime" : "2019-06-03T17:06:12+02:00",
    "fulfilmentMethod" : "FBR",
    "returnItems" : [ {
      "rmaId" : "60283608",
      "orderId" : "1044796550",
      "ean" : "0634154562956",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Anders, namelijk:",
        "customerComments" : "Cadeau vonden ze niet leuk"
      },
      "handled" : false
    } ]
  } ]
}

Get a single item return created by the customer and handled by the retailer

Retrieve a single return for FBR order 1020824520 with a handling result RETURN_RECEIVED.

GET /retailer-demo/returns/15892026

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returnId" : "15892026",
  "registrationDateTime" : "2018-11-06T10:48:34+01:00",
  "fulfilmentMethod" : "FBR",
  "returnItems" : [ {
    "rmaId" : "60278123",
    "orderId" : "1020824520",
    "ean" : "5702015866736",
    "title" : "LEGO DUPLO Cars Piston Cup Race - 10857",
    "expectedQuantity" : 1,
    "returnReason" : {
      "mainReason" : "Geen reden"
    },
    "handled" : true,
    "processingResults" : [ {
      "quantity" : 1,
      "processingResult" : "ACCEPTED",
      "handlingResult" : "RETURN_RECEIVED",
      "processingDateTime" : "2018-11-06T10:48:38+01:00"
    } ],
    "customerDetails" : {
      "salutation" : "UNKNOWN",
      "zipCode" : "1234BV",
      "countryCode" : "NL",
      "email" : "2wb3y4vqq667avck657zbhx2uevm7a@verkopen.test2.bol.com"
    }
  } ]
}

Get all handled returns

Retrieves all handled returns, which are sorted by date of processing in descending order. Each return item shows the exact handling and processing result for each item.

GET /retailer-demo/returns?handled=true

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returns" : [ {
    "returnId" : "15897410",
    "registrationDateTime" : "2019-06-03T17:06:12+02:00",
    "fulfilmentMethod" : "FBR",
    "returnItems" : [ {
      "rmaId" : "60283607",
      "orderId" : "1044796550",
      "ean" : "0634154562079",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Verkeerde maat of formaat",
        "customerComments" : "Verkeerde maat of formaat"
      },
      "handled" : true
    } ]
  }, {
    "returnId" : "15896813",
    "registrationDateTime" : "2019-05-09T13:04:22+02:00",
    "fulfilmentMethod" : "FBR",
    "returnItems" : [ {
      "rmaId" : "60282944",
      "orderId" : "1043965710",
      "ean" : "0811571016532",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Verkeerd artikel ontvangen",
        "customerComments" : "Verkeerd artikel ontvangen"
      },
      "handled" : true
    }, {
      "rmaId" : "60282945",
      "orderId" : "1044194100",
      "ean" : "3138520283072",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Artikel is defect/werkt niet",
        "customerComments" : "Artikel is defect/werkt niet"
      },
      "handled" : true
    } ]
  }, {
    "returnId" : "15892026",
    "registrationDateTime" : "2018-11-06T10:48:34+01:00",
    "fulfilmentMethod" : "FBR",
    "returnItems" : [ {
      "rmaId" : "60278123",
      "orderId" : "1020824520",
      "ean" : "5702015866736",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Geen reden",
        "customerComments" : "Geen reden"
      },
      "handled" : true
    } ]
  } ]
}

Get all handled returns for FBB orders

Retrieves all handled returns that were 'Fulfillment by bol.com', which are sorted by date of processing in descending order. Each return item shows the exact handling and processing result for the item.

GET /retailer-demo/returns?fulfilment-method=FBB&handled=true

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returns" : [ {
    "returnId" : "5",
    "registrationDateTime" : "2018-04-27T19:55:12+02:00",
    "fulfilmentMethod" : "FBB",
    "returnItems" : [ {
      "rmaId" : "86127199",
      "orderId" : "7616247328",
      "ean" : "8718526069334",
      "expectedQuantity" : 1,
      "returnReason" : {
        "mainReason" : "Verkeerd besteld",
        "customerComments" : "Ik wilde eigenlijk een groter formaat"
      },
      "handled" : true,
      "processingResults" : [ {
        "quantity" : 1,
        "processingResult" : "ACCEPTED",
        "handlingResult" : "RETURN_RECEIVED",
        "processingDateTime" : "2019-05-02T10:45:20+02:00"
      }, {
        "quantity" : 1,
        "processingResult" : "ACCEPTED",
        "handlingResult" : "RETURN_RECEIVED",
        "processingDateTime" : "2019-05-02T10:45:20+02:00"
      } ]
    } ]
  } ]
}

Get a multi-item return where both returns are handled

Retrieve a multi-item return for FBR order 1044796550 where 1 item is handled and 1 item is unhandled.

GET /retailer-demo/returns/15897410

  • Request

  • Response

Accept: application/vnd.retailer.v10+json
Content-Type: None
Authorization: Bearer token (omitted)

This endpoint has no request body.

Content-Type: application/vnd.retailer.v10+json

Status: 200 OK

{
  "returnId" : "15897410",
  "registrationDateTime" : "2019-06-03T17:06:12+02:00",
  "fulfilmentMethod" : "FBR",
  "returnItems" : [ {
    "rmaId" : "60283607",
    "orderId" : "1044796550",
    "ean" : "0634154562079",
    "title" : "Bookwallet lederlook hoes Google Pixel XL groen",
    "expectedQuantity" : 1,
    "returnReason" : {
      "mainReason" : "Verkeerde maat of formaat",
      "customerComments" : "Verkeerde maat of afmeting > Te klein"
    },
    "trackAndTrace" : "12ABCD345678900",
    "transporterName" : "PostNL",
    "handled" : true,
    "processingResults" : [ {
      "quantity" : 1,
      "processingResult" : "ACCEPTED",
      "handlingResult" : "RETURN_RECEIVED",
      "processingDateTime" : "2019-06-03T17:06:31+02:00"
    } ],
    "customerDetails" : {
      "salutation" : "MALE",
      "firstName" : "Luke",
      "surname" : "Skywalker",
      "streetName" : "Acmestraat",
      "houseNumber" : "1",
      "zipCode" : "1234AB",
      "city" : "Acme City",
      "countryCode" : "NL",
      "email" : "2wb3y4vqq667avck657zbhx2uevm7a@verkopen.test2.bol.com",
      "company" : "Company Corp"
    }
  }, {
    "rmaId" : "60283608",
    "orderId" : "1044796550",
    "ean" : "0634154562956",
    "title" : "Bookwallet lederlook hoes Sony Xperia XZ bruin",
    "expectedQuantity" : 1,
    "returnReason" : {
      "mainReason" : "Anders, namelijk:",
      "customerComments" : "Ik heb me bedacht"
    },
    "trackAndTrace" : "3SBLCR102648846",
    "transporterName" : "PostNL",
    "handled" : false,
    "customerDetails" : {
      "salutation" : "MALE",
      "firstName" : "Luke",
      "surname" : "Skywalker",
      "streetName" : "Acmestraat",
      "houseNumber" : "1",
      "zipCode" : "1234AB",
      "city" : "Acme City",
      "countryCode" : "NL",
      "email" : "2wb3y4vqq667avck657zbhx2uevm7a@verkopen.test2.bol.com",
      "company" : "Company Corp"
    }
  } ]
}