> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dhmad.tn/llms.txt
> Use this file to discover all available pages before exploring further.

# Deliver Escrow

> Mark an escrow as delivered by the seller

<Endpoint method="POST" path="/api/v1/escrows/:id/deliver" />

Mark an escrow as delivered. Only the **seller** can perform this action, and the escrow must be in `paid` status (i.e., the buyer has already paid).

* **Standard mode:** After delivery, the escrow moves to `delivered` status and the buyer is notified. The buyer must then confirm delivery to release funds to the seller.
* **Quick mode:** Same as standard after delivery — escrow moves to `delivered` and the buyer must confirm via checkout (`complete` action) or on dhmad.tn.
* **Instant mode:** Calling deliver **auto-completes** the escrow and releases funds to you immediately. The escrow moves directly from `paid` to `completed`; there is no buyer confirmation step. The response message will indicate that the escrow was delivered and completed (instant mode).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/deliver \
    -H "Authorization: Bearer sk_live_your_api_key_here" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/deliver', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key_here',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "message": "Escrow marked as delivered",
    "escrow": {
      "id": "507f1f77bcf86cd799439011",
      "title": "Web Development Service",
      "amount": 1000.00,
      "status": "delivered",
      "deliveredAt": "2024-01-20T14:00:00Z",
      "completionDeadline": "2024-01-27T14:00:00Z",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-20T14:00:00Z"
    }
  }
  ```
</ResponseExample>

For **instant** mode escrows, the response is:

```json theme={null}
{
  "message": "Escrow delivered and completed (instant mode). Funds released.",
  "escrow": { "id": "...", "status": "completed", "deliveredAt": "...", "completedAt": "...", ... }
}
```

## Path Parameters

<ParamField path="id" type="string" required>
  Escrow ID
</ParamField>

## Response Fields

<ParamField response="message" type="string">
  Success message
</ParamField>

<ParamField response="escrow" type="object">
  Updated escrow object with status `delivered`, `deliveredAt`, and `completionDeadline`
</ParamField>

## Error Responses

### 400 Bad Request

**Escrow Not Paid**

```json theme={null}
{
  "error": "Bad Request",
  "message": "Escrow must be in paid status before delivery"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized"
}
```

### 403 Forbidden

**Only Seller Can Deliver**

```json theme={null}
{
  "error": "Forbidden",
  "message": "Only the seller can mark an escrow as delivered"
}
```

### 404 Not Found

```json theme={null}
{
  "error": "Escrow not found"
}
```

***

<Warning>
  Only the **seller** can mark an escrow as delivered. Your developer account must be associated with the seller's user account. If you are the buyer, you cannot call this endpoint.
</Warning>

<Info>
  **Standard and quick modes:** After delivery, the buyer receives a notification and can confirm completion to release funds. Use the checkout session with `complete` action if you need to redirect the buyer to confirm delivery on dhmad.tn. **Instant mode:** Deliver auto-completes and releases funds; no buyer confirmation or checkout session for `complete` is needed.
</Info>