Skip to main content

Request refunds by API

It's rare, but sometimes a delivery doesn't go according to plan. Our Support team may issue refunds if there is an issue with a delivery. You can also request refunds programmatically using our refunds API. If you're a middleware or technology provider that serves many merchants via a self-serve app/website, you can use this API to build a self-serve refunds experience into that app/website. Refunds are evaluated according to the refund matrix.

1. Prerequisites

If you're new to Drive and haven't yet created your first delivery, you should start with one of our tutorials. The tutorials will walk you through getting the credentials you need to call the APIs and making some basic API calls.

2. Build a self-serve refund flow into your app

To use the self-serve refunds API, you must build a merchant-facing refund flow into your application. We require that the self-serve refund is initiated on behalf of the merchant from which the delivery was picked up. Your refund flow must ask the requestor to select a reason for requesting a refund:

  • Order Cancelled (cancelled_order): the order was cancelled by the customer or the merchant
  • Never Delivered (never_delivered): the order was picked up but never delivered
  • Order Delivered Late (delivered_late): the order arrived after the TODO
  • Order Delivered Early (delivered_early): the order arrived before the TODO
  • Poor Delivery Experience (poor_delivery_experience): the Dasher was unprofessional TODO
  • Entire Order Wrong (entire_order_wrong): the wrong order was picked up and delivered to the wrong customer
  • Missing Main (missing_main): one main dish was missing from the delivery
  • Missing Side (missing_side): one side dish was missing from the delivery
  • Incorrect Items (incorrect_items): multiple main or side dishes were missing from the delivery

3. Request a refund

Under the hood, the self-serve refund flow in your application should call the Refunds API to request a refund.

POST /drive/v2/deliveries/{external_delivery_id}/refunds

{
// use this field to pass the refund reason selected in your self-serve flow
"refund_reason": "cancelled_order",
}

4. Show the refund results in your app

The response to your refund request will include information on the refund decision. Your app must show these details to the requestor of the refund:

  • status: DoorDash's decision on the refund
  • code: DoorDash's decision on the category that applies to the refund; see the full list of codes in the Refunds API reference
  • message: a human-friendly string that describes the refund decision
  • order_value_refund: the amount of the order value that was refunded; like all currency amounts, this will be specified in cents (or the equivalent lowest currency denomination)
  • tip_refund: the amount of the tip that was refunded; like all currency amounts, this will be specified in cents (or the equivalent lowest currency denomination)
  • delivery_fee_refund: the amount of the delivery fee that was refunded; like all currency amounts, this will be specified in cents (or the equivalent lowest currency denomination)

Next steps

  • Learn how and when DoorDash provides refunds using the refund matrix