Skip to main content
Buyer rejects the seller’s delivery. The escrow reverts from delivered to paid so the seller can fix issues and deliver again. Funds stay locked — this does not release or move money. Only the buyer can perform this action, and the escrow must be in delivered status. Not applicable to instant mode escrows (which skip the delivered status). 
curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/reject-delivery \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"reason": "One item was missing from the shipment."}'

{
  "message": "Delivery rejected. Escrow returned to paid status.",
  "escrow": {
    "id": "507f1f77bcf86cd799439011",
    "title": "Web Development Service",
    "amount": 1000.00,
    "status": "paid",
    "deliveredAt": null,
    "completionDeadline": null,
    "deliveryRejections": [
      {
        "rejectedAt": "2024-01-21T10:00:00Z",
        "reason": "One item was missing from the shipment.",
        "previousDeliveredAt": "2024-01-20T14:00:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-21T10:00:00Z"
  }
}

​
Path Parameters

​
id
string
required
Escrow ID

​
Request Body

​
reason
string
Optional feedback for the seller explaining what needs to be fixed

​
Response Fields

​
Error Responses

​
400 Bad Request

Escrow Not Delivered 
{
  "error": "Bad Request",
  "message": "Escrow must be in delivered status to reject delivery"
}
Open Dispute 
{
  "error": "Bad Request",
  "message": "Cannot reject delivery while a dispute is open"
}

​
401 Unauthorized

{
  "error": "Unauthorized"
}

​
403 Forbidden

Only Buyer Can Reject 
{
  "error": "Forbidden",
  "message": "Only the buyer can reject delivery for this escrow"
}

​
404 Not Found

{
  "error": "Escrow not found"
}
Only the buyer can reject delivery. Your developer account must be associated with the buyer’s user account. If you are the seller, you cannot call this endpoint.
After rejection, the seller can call Deliver Escrow again when ready. The buyer can still open a dispute if issues cannot be resolved.Subscribe to escrow.delivery.rejected in your webhook to receive the buyer’s optional reason, plus escrow.status.updated (delivered → paid).