Merchant Order Returns

Implement Merchant order returns

🚧 Retail-only feature
This endpoint is intended for Merchant Pick (Retail) integrations only and is not supported for Restaurant (Rx) use cases.

Prerequisites

The return notification endpoint accepts a DoorDash order ID in the URL. The body lists returned line items (with quantities), optional per-item return reasons, and the store where the return was accepted.

Overview

This flow applies to the Merchant Pick fulfillment model. Integration for DoorDash Retail UI describes how this fits with other retail fulfillment patterns. For that model, customer payment is not processed at pickup; the endpoint records an in-store return so DoorDash can run refund and payout reconciliation.

A successful request:

• Records which items and quantities were returned
• Records the store (return_location_id) where the return was accepted

The same endpoint supports partial and full returns.

⚠️ Key Constraints

One return request per order

Only one return request is supported per order.

• All returned items and quantities must be included in a single request
• Any additional return attempts for the same order will fail with a 409 Duplicate return request error

This limitation is due to downstream refund processing constraints.

No updates after submission

Return requests cannot be modified or updated after submission.

Implementation Guidance

To avoid failed requests and ensure accurate refunds:

• Aggregate all return items before calling the API
  • Do not send multiple requests for the same order
• Call the endpoint only after the full return is completed in-store
• If a customer attempts to return additional items later:
  • These cannot be processed via this API
  • Handle these cases through manual or off-platform workflows

Get Started

---

Step 1:

Reach out to your technical account manager to confirm your integration is allowlisted for order return notifications.

Step 2:

Send return requests using the format below and handle the response from DoorDash.

Return Order endpoint

POST https://openapi.doordash.com/marketplace/api/v1/orders/{id}/return

Request fields

return_items (required) — Array of objects. Each object represents an item being returned.

Field	Type	Required	Description
merchant_supplied_id	string	Yes	Merchant-supplied identifier for the item
quantity	integer	Yes	Quantity of the item being returned
reason	string	No	Reason for the return; must be a supported enum if present

return_location_id (required) — String. Identifier for the store where the return was accepted.

ℹ️ return_location_id should match the same store identifier used as store_location_id in other DoorDash APIs.

Return reason enum

If provided, reason must be one of:

• incorrect_item_received
• dashmart_only_item_not_found
• incorrect_size_or_weight
• incorrect_quantity
• sub_not_satisfactory
• item_not_received
• missing_item
• incorrect_size
• poorly_packaged_or_handled
• shopped_item_not_fresh
• did_not_meet_expectations
• other

Example payload

{
  "return_items": [
    {
      "merchant_supplied_id": "item-123",
      "quantity": 1,
      "reason": "incorrect_item_received"
    }
  ],
  "return_location_id": "5451"
}

Response

Response	Description
202	Return request was received successfully and queued for processing

ℹ️ Returns are processed asynchronously. A 202 response indicates the request was accepted, not completed.

Example 202 body:

{
  "operation_id": "8a718033-c12c-4d08-9376-0f4a96e4ac08",
  "operation_status": "QUEUED",
  "message": "Return request received."
}

Field	Type	Description
operation_id	string	Unique identifier for the return request
operation_status	string	Status of the return request
message	string	Informational message

Error codes

Response	Description
400	Validation failed (e.g., missing or bad fields)
401	Unauthorized
403	Forbidden
404	Order not found
409	Duplicate return request
429	Rate limit exceeded
500	Internal server error

Example 400 validation error body:

{
  "code": "VALIDATION_ERROR",
  "message": "One or more request values couldn't be validated.",
  "field_errors": [
    {
      "field": "return_items.quantity",
      "error": "item quantity must be greater than 0"
    }
  ]
}

Generic error example:

{
  "code": "items_do_not_belong_to_order",
  "message": "All return items do not belong to the order"
}

409 Duplicate return request

This error occurs when:

• A second return request is submitted for the same order
• A return request has already been processed or is in progress

Because only one return request is allowed per order, subsequent attempts will always fail.

FAQs

When should we call this endpoint?

Call this endpoint after the in-store return is fully completed, when:

• Items are physically returned to the store
• Final return quantities are confirmed

Do not call this endpoint incrementally or per item.

---

How do refunds work after a return is submitted?

Refunds are processed by DoorDash after the return is approved.

• DoorDash credit refunds: typically instant
• Original payment method (e.g., card): typically 1–3 business days

Refunded amounts are withheld from the merchant’s next payout.
Customer notifications and refund methods are handled by DoorDash.

---

Are there limits or validation rules we should know about?

• Returned quantities must not exceed the purchased quantity
• Items must belong to the specified order
• Only one return request is allowed per order
• Duplicate or subsequent return attempts will fail with a 409 error

---

Is there a return window enforced by DoorDash?

No. Return eligibility (timing, policy, etc.) is determined by the merchant.

Merchants should validate return eligibility before calling this endpoint.

---

Can a return request be updated or retried?

No. Return requests cannot be updated after submission.

If a request fails due to validation errors, it can be retried with corrected data.
If a request succeeds, additional returns cannot be submitted for that order.

---

last modified 5/1/2026