Identifying a failed delivery for refunding the customer

In the API docs there’s a section on the reason_key which may be sent along with a Job Status of canceled or a Delivery Status of cancelled.

There are some reason_keys which appear in both the list of keys which indicate no further action will be taken, and the list of keys which indicate further action will be taken:


Can you clarify why they appear in both, and what the possible actions taken could be?

Also, with regards to the list of reasons which which do indicate further action, can you confirm which of the reason_keys could result in the job / delivery status changing again - i want to make sure i only refund the customer if i am certain that the job/delivery will stay cancelled and a new one will not be created.

Hello @gluis11,

Indeed some of our cancellation reason keys could relate to more than one situation, these reasons originate from actions that our Support teams can preform on an order and the reason they may select for performing that action. This page aims to document which combination of order status and reason keys reflect whether an order will, or will not, have further actions. The further actions refer to driver reassignment, manual stacking, or the returning of the package to the pickup.

To take an example, ‘incorrect_package’ is likely to signify a return if the package has already been picked up by the driver, in this scenario the driver may realise whilst on route that he has the wrong package. On the other hand ‘incorrect_package’ could signify an order cancellation with no further actions in a case where the package was identified as incorrect at handover and the order could no longer be fulfilled.

From your question, I believe you want to know when an order is truly cancelled, including returns, where the order did not make it to the customer, is that correct? (meaning you’d refund the customer whenever they don’t receive the order)

In that case we can refund the client if the delivery status is ‘cancelled’ and the reason key is not ‘manually_stacked’. Note that for returns the final status will be ‘delivered’, signifying successful return back to store, so you’d need to determine the refund is required when the return is initially triggered - when the status is ‘cancelled’.

Thanks for the reply. The incorrect_package scenario was useful to help me understand.

Just to clarify, if i get a webhook where:

  • event is delivery
  • type is update
  • data.status is cancelled
  • data.cancellation.reasonKey is anything other than manually_stacked

this means that the customer won’t be receiving their delivery and therefor it is safe for me to refund the customer?

And if i get any other webhook, it is possible that the customer could still receive their package, so i shouldn’t refund the customer (it is not possible for us to cancel a refund so i want to only issue a refund when i can be certain that they won’t receive the package)?

Hi @gluis11,

You’re very welcome, i’m glad the description helped. I agree this is a complex topic!

Yes that’s right, so long as we only determine the refund from the update which has the ‘cancelled’ status then this should be fine. For the return case you can expect more updates after this ‘cancelled’ status, but the client will still not receive the package because it’s being returned to store.

For these returned or cancelled packages, the only way that the customer could still receive the package is if you send another job creation request over to us to take a second attempt at delivery.

1 Like