> ## 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.

# Cancel Escrow

> Cancel a pending escrow before payment

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

Cancel an escrow that is still in `pending` status (before the buyer has paid). Both the seller and buyer can cancel a pending escrow via the API. For **paid or delivered** escrows, **buyers** use a `request_cancellation` checkout session; **sellers** use a `cancel_escrow` checkout session.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/cancel \
    -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/cancel', {
    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 cancelled successfully",
    "escrow": {
      "id": "507f1f77bcf86cd799439011",
      "title": "Web Development Service",
      "amount": 1000.00,
      "status": "cancelled",
      "cancelledAt": "2024-01-16T10:00:00Z",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-16T10:00:00Z"
    }
  }
  ```
</ResponseExample>

## 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 `cancelled` and `cancelledAt` timestamp
</ParamField>

## Error Responses

### 400 Bad Request

**Escrow Not Pending**

```json theme={null}
{
  "error": "Bad Request",
  "message": "Only pending escrows can be cancelled via API. For paid or delivered escrows, buyers use a request_cancellation checkout session; sellers use a cancel_escrow checkout session."
}
```

### 401 Unauthorized

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

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden",
  "message": "Developer account must be associated with a user account. Please associate your account in the developer dashboard."
}
```

### 404 Not Found

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

***

<Warning>
  This endpoint only works on escrows in `pending` status. Once the buyer has paid, use checkout sessions: **`request_cancellation`** (buyer email) for buyer-initiated cancellation, or **`cancel_escrow`** (seller email) for seller direct cancellation. The seller may also accept or reject a pending buyer request via **`accept_cancellation`** / **`reject_cancellation`** checkout sessions.
</Warning>

<Note>
  Both the seller and buyer can cancel a pending escrow. The other party will receive a notification when the escrow is cancelled.
</Note>