Delivery returns

A partner can request for a delivery to be returned to the collection point by the rider in case they are unable to deliver the cargo.

This can happen if the customer is unavailable, the address unreachable etc ...

How to set a delivery as returnable ?

The features field in the Accept quote endpoint is used to signal whether to mark the delivery as returnable or not.

If not set, the delivery is created as non-returnable by default

If the partner explicitly provides the features field with the RETURNABLE value, the delivery will be created as returnable and the rider will be prompted to return the cargo to the collection point if the delivery fails.
A rider has 24h starting from return creation time to return the cargo to the collection point.

How do I get notified of a return status ?

When a return is initiated, updates on the progress of the rider are sent via the riders.update_status webhook events (see Rider webhook documentation for more details)

The delivery_type will be used to differentiate between the status updates of the main delivery and the return one.

For the main delivery, the rider update message will have the delivery_type field set to MAIN

{
  "event": "riders.update_status",
  "body": {
    "delivery_id": "f7e458ec-3d8e-4271-9a25-34d2fa125782",
    "external_ref_id": "6823e970-283d-4bfd-849e-7bcb0e4a1b40#courier",
    "riders": [
		{
			"rider_id": "4d50561f-2950-44e3-af7a-f7c60a6a014e",
			"delivery_type": "MAIN",
			"status": {
			    "effective_at": "2024-01-01T08:00:00.52Z",
			    "status": "CONFIRMED_AT_CUSTOMER"
			}
		}
	]
  }
}

The return rider update message will have a RETURN value for the delivery_type field

{
  "event": "riders.update_status",
  "body": {
    "delivery_id": "f7e458ec-3d8e-4271-9a25-34d2fa125782",
    "external_ref_id": "6823e970-283d-4bfd-849e-7bcb0e4a1b40#courier",
    "riders": [
		{
			"rider_id": "4d50561f-2950-44e3-af7a-f7c60a6a014e",
			"delivery_type": "RETURN",
			"status": {
			    "effective_at": "2024-01-01T08:10:00.52Z",
			    "status": "EN_ROUTE_TO_SITE"
			}
		}
	]
  }
}

Please note that the rider status will be absolute and not relative to the delivery direction regardless of the direction of the delivery.

For example, EN_ROUTE_TO_SITE for a main delivery means that the rider has accepted the delivery and is making their way to the collection point to retrieve the cargo before heading to the customer.

EN_ROUTE_TO_SITE in the case of a return delivery means that the rider has started the return journey from the customer towards the collection point and is now heading to the site to drop off the cargo that they couldn't deliver.

How much will I be billed for the return ?

The return fee can be found in the Request preliminary quote endpoint response in the additional_fees field

The return_fee will be provided. The partner can then check if the fee is acceptable and proceed to Accept the quote if it is

{
  "additional_fees": {
    "return_fee": {
      "currency": "GBP",
      "fractional": 500
    }
  }
}

The accepted return_fee will also be returned by the Check delivery and Query existing quote endpoints.