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

# List Payout Requests

> Full period history and live reservation figures for a progressive-release escrow

<Endpoint method="GET" path="/api/v1/escrows/:id/release-requests" />

Return every payout request on a **progressive-release** escrow, with each period's status, deadline and admin resolution. The response also carries the live **face + TND** reservation figures (and `fundedAmount*` / `remainingAmount*` / `refundedTotal*`), so you can size the next period and reconcile without inventing FX.

Use this to reconcile your own timesheet records — for example after a webhook delivery failure, or when rebuilding state on a scheduled job.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/release-requests \
    -H "Authorization: Bearer sk_live_your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/release-requests',
    {
      headers: { 'Authorization': 'Bearer sk_live_your_api_key_here' }
    }
  );

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

<ResponseExample>
  ```json theme={null}
  {
    "releaseRequests": [
      {
        "requestId": "timesheet-2026-W10",
        "reference": "Week 10 (Mar 2-8)",
        "amountTnd": 67.61,
        "amountFace": 24,
        "currency": "USD",
        "status": "released",
        "createdVia": "api",
        "approvalDeadline": "2026-03-11T09:00:00Z",
        "sellerNetTnd": 63.55,
        "decidedAt": "2026-03-10T14:22:00Z",
        "decisionSource": "buyer",
        "releasedAt": "2026-03-10T14:22:01Z",
        "createdAt": "2026-03-09T09:00:00Z"
      },
      {
        "requestId": "timesheet-2026-W12",
        "reference": "Week 12 (Mar 16-22)",
        "amountTnd": 67.61,
        "amountFace": 24,
        "currency": "USD",
        "status": "disputed",
        "createdVia": "api",
        "approvalDeadline": "2026-03-25T09:00:00Z",
        "decidedAt": "2026-03-24T11:05:00Z",
        "decisionSource": "buyer",
        "disputeTicketId": "6612f1a8bcf86cd7994390aa",
        "createdAt": "2026-03-23T09:00:00Z"
      }
    ],
    "progressiveRelease": {
      "enabled": true,
      "autoApproveHours": 48,
      "minReleaseTnd": 5,
      "buyerConsentAcceptedAt": "2026-03-01T10:00:00Z"
    },
    "availableForRelease": 272,
    "reserved": 24,
    "releasedTotal": 24,
    "reservedTnd": 67.61,
    "availableForReleaseTnd": 766.23,
    "releasedTotalTnd": 67.61,
    "fundedAmount": 320,
    "fundedAmountTnd": 901.45,
    "remainingAmount": 296,
    "remainingAmountTnd": 833.84,
    "refundedTotal": 0,
    "refundedTotalTnd": 0,
    "escrowStatus": "paid"
  }
  ```
</ResponseExample>

## Path Parameters

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

## Response Fields

<ParamField response="releaseRequests" type="array">
  Every payout request on the escrow, oldest first
</ParamField>

<ParamField response="releaseRequests[].requestId" type="string">
  Your identifier for the period
</ParamField>

<ParamField response="releaseRequests[].amountTnd" type="number">
  Slice amount in ledger TND
</ParamField>

<ParamField response="releaseRequests[].amountFace" type="number">
  Slice amount in escrow face currency
</ParamField>

<ParamField response="releaseRequests[].currency" type="string">
  Face currency for `amountFace`
</ParamField>

<ParamField response="releaseRequests[].status" type="string">
  One of `pending`, `approved`, `disputed`, `released`, `voided`. There is no `rejected` state — a client rejection goes straight to `disputed` so the period always has a resolution path.
</ParamField>

<ParamField response="releaseRequests[].approvalDeadline" type="string">
  When a `pending` request auto-approves
</ParamField>

<ParamField response="releaseRequests[].sellerNetTnd" type="number">
  What the seller receives for this slice, after platform and developer fees
</ParamField>

<ParamField response="releaseRequests[].decisionSource" type="string">
  `buyer` (client decided), `timeout` (auto-approved at the deadline), or `admin` (dispute resolution)
</ParamField>

<ParamField response="releaseRequests[].disputeTicketId" type="string">
  Set when the period is disputed. Scoped to this period only — it does not flag the whole escrow as disputed.
</ParamField>

<ParamField response="releaseRequests[].resolution" type="object">
  Present after a disputed period is resolved: `awardedTnd`, `resolvedAt`, and `reason`. An award below the claim returns the remainder to the available balance.
</ParamField>

<ParamField response="availableForRelease" type="number">
  Claimable balance in face currency
</ParamField>

<ParamField response="reserved" type="number">
  Open reservations in face currency
</ParamField>

<ParamField response="releasedTotal" type="number">
  Cumulative face amount paid out
</ParamField>

<ParamField response="reservedTnd" type="number">
  Balance claimed by open requests (pending, approved and disputed)
</ParamField>

<ParamField response="availableForReleaseTnd" type="number">
  Balance a new payout request may claim
</ParamField>

<ParamField response="releasedTotalTnd" type="number">
  Cumulative TND paid out through partial releases
</ParamField>

<ParamField response="fundedAmount" type="number">
  Stable funded principal in face currency
</ParamField>

<ParamField response="fundedAmountTnd" type="number">
  Stable funded principal in TND
</ParamField>

<ParamField response="remainingAmount" type="number">
  Live remaining float in face currency (`0` when terminal)
</ParamField>

<ParamField response="remainingAmountTnd" type="number">
  Live remaining float in TND (`0` when terminal)
</ParamField>

<ParamField response="refundedTotal" type="number">
  Face amount returned unused
</ParamField>

<ParamField response="refundedTotalTnd" type="number">
  TND returned unused
</ParamField>

## Error Responses

### 401 Unauthorized

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

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden",
  "message": "Only a party on this escrow can manage payout requests"
}
```

### 404 Not Found

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

***

<Info>
  A non-progressive escrow returns an empty `releaseRequests` array with `progressiveRelease: null`, rather than an error.
</Info>