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

# Create Payout Request

> Claim one billing period from a progressive-release escrow

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

Claim a slice of a funded **progressive-release** escrow — one request per billing period, such as a weekly timesheet on an hourly contract. The escrow must have been created with a `progressiveRelease` object.

You can call this **on the seller's behalf** when your application created the escrow, so the freelancer takes no weekly action. The amount is reserved against the escrow balance immediately, the client is notified, and the request releases automatically once `approvalDeadline` passes unless the client decides first.

**What the client can do:**

* **Approve** — the period is released to the seller's DHMAD balance right away (`approve_release` checkout session).
* **Reject** — a dispute is opened for *that period only*. The amount stays reserved and protected while DHMAD reviews it; later periods keep running normally (`reject_release` checkout session).
* **Nothing** — the request auto-approves and releases at the deadline.

<Note>
  `requestId` is your idempotency key. Repeating a request with the same `requestId` returns the existing one with `200` instead of reserving twice, so an at-least-once weekly job is safe to retry.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/release-requests \
    -H "Authorization: Bearer sk_live_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "requestId": "timesheet-2026-W12",
      "amount": 24.00,
      "currency": "USD",
      "reference": "Week 12 (Mar 16-22)"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/release-requests',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        requestId: 'timesheet-2026-W12',
        amount: 24.0,
        currency: 'USD',
        reference: 'Week 12 (Mar 16-22)'
      })
    }
  );

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

<ResponseExample>
  ```json theme={null}
  {
    "message": "Payout request created",
    "idempotentReplay": false,
    "releaseRequest": {
      "requestId": "timesheet-2026-W12",
      "amountTnd": 67.61,
      "amountFace": 24,
      "currency": "USD",
      "approvalDeadline": "2026-03-25T09:00:00Z",
      "status": "pending"
    },
    "availableForRelease": 296,
    "reserved": 24,
    "releasedTotal": 0,
    "availableForReleaseTnd": 833.84,
    "reservedTnd": 67.61,
    "releasedTotalTnd": 0,
    "fundedAmount": 320,
    "fundedAmountTnd": 901.45,
    "remainingAmount": 320,
    "remainingAmountTnd": 901.45,
    "refundedTotal": 0,
    "refundedTotalTnd": 0,
    "escrowStatus": "paid"
  }
  ```
</ResponseExample>

## Path Parameters

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

## Body Parameters

<ParamField body="requestId" type="string" required>
  Your own identifier for this period, unique per escrow. Doubles as the idempotency key. Letters, numbers and `. _ : -` only (max 120 characters).
</ParamField>

<ParamField body="amountTnd" type="number">
  The slice in ledger TND. Provide this **or** face `amount`. Required unless `amount` is provided.
</ParamField>

<ParamField body="amount" type="number">
  The slice in the escrow's face currency (e.g. `24.00` USD). DHMAD converts with
  the escrow's locked FX — partners need not invent TND. Ignored when `amountTnd`
  is present.
</ParamField>

<ParamField body="currency" type="string">
  `TND`, `USD` or `EUR`. Must match the escrow currency when sending face `amount`.
  Defaults to the escrow's currency.
</ParamField>

<ParamField body="reference" type="string">
  Your own period label, shown to both parties and printed on the fiscal invoice for this release (max 200 characters).
</ParamField>

<ParamField body="note" type="string">
  Optional internal note (max 500 characters).
</ParamField>

## Response Fields

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

<ParamField response="idempotentReplay" type="boolean">
  `true` when a request with this `requestId` already existed and was returned unchanged. The status code is `200` rather than `201`.
</ParamField>

<ParamField response="releaseRequest.requestId" type="string">
  Your identifier for this period
</ParamField>

<ParamField response="releaseRequest.amountTnd" type="number">
  Reserved amount in TND
</ParamField>

<ParamField response="releaseRequest.amountFace" type="number">
  Reserved amount in escrow face currency
</ParamField>

<ParamField response="releaseRequest.currency" type="string">
  Escrow face currency for `amountFace`
</ParamField>

<ParamField response="releaseRequest.approvalDeadline" type="string">
  ISO timestamp. The request auto-approves and releases after this instant unless decided first.
</ParamField>

<ParamField response="releaseRequest.status" type="string">
  `pending` on creation
</ParamField>

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

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

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

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

<ParamField response="availableForReleaseTnd" type="number">
  What a further payout request may still claim (`amountTnd` − `reservedTnd`)
</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>

## Error Responses

### 400 Bad Request

**Progressive release not enabled**

```json theme={null}
{
  "error": "Bad Request",
  "code": "PROGRESSIVE_RELEASE_NOT_ENABLED",
  "message": "Progressive release is not enabled for this escrow."
}
```

**Seller identity not verified**

```json theme={null}
{
  "error": "Bad Request",
  "code": "SELLER_IDENTITY_REQUIRED",
  "message": "The seller must complete identity verification before payouts can be requested."
}
```

**Amount below the minimum slice**

```json theme={null}
{
  "error": "Bad Request",
  "code": "AMOUNT_TOO_SMALL",
  "message": "Release amount must be at least 5 TND."
}
```

### 409 Conflict

**Insufficient unreserved balance**

```json theme={null}
{
  "error": "Bad Request",
  "code": "INSUFFICIENT_AVAILABLE_BALANCE",
  "message": "Insufficient unreserved balance for this payout request (available 120.5 TND).",
  "availableForReleaseTnd": 120.5,
  "reservedTnd": 3879.5
}
```

**Client has not accepted automatic release**

```json theme={null}
{
  "error": "Bad Request",
  "code": "CONSENT_REQUIRED",
  "message": "The client has not accepted automatic release for this contract."
}
```

### 401 Unauthorized

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

### 404 Not Found

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

***

<Info>
  Because the seller identity check runs at **creation** rather than at payout, requests never pile up unpayable. The check is idempotent, so once the freelancer is verified and linked it passes for every future period — there is no weekly friction.
</Info>

<Warning>
  When the balance runs out the escrow stays open and DHMAD emits `escrow.balance.exhausted`. Pause tracking and prompt the client to top up with an `add_funds` checkout session; do not close the contract.
</Warning>