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

# Milestone escrows

> Fund a project upfront and release it in stages as each milestone is confirmed.

A **milestone escrow** holds the full amount upfront and releases it in parts as
the buyer confirms each milestone. It has `settlementType: MILESTONE` and
carries a `milestones[]` array.

This suits multi-stage work (design → build → deploy) where the buyer wants to
release payment progressively as deliverables land.

## Rules

When you call [Create milestone escrow](/api-reference/milestone-escrow/create-milestone-escrow):

<Check>At least **2 milestones** are required.</Check>
<Check>Every milestone `amount` must be a **positive integer**.</Check>
<Check>The **sum of milestone amounts must equal** the escrow `amount`.</Check>
<Check>`whoPays` must be **`buyer`**: the buyer always covers the Payluk fee on milestone escrows.</Check>
<Check>The **`customer-id` header is required**, identifying the customer the escrow is created on behalf of.</Check>

Each milestone may also carry an **optional `customerId`**: the beneficiary
who should receive that milestone's funds. When set, releasing the milestone
credits that customer's main balance instead of the seller's (see
[How funds release](#how-funds-release) below).

Unlike standard escrows, milestone creation uses a **JSON** body (no file
upload).

```json theme={null}
{
  "amount": 1000000,
  "purpose": "Company website build",
  "whoPays": "buyer",
  "milestones": [
    { "title": "Design",      "amount": 300000, "dueDate": "2026-07-15", "customerId": "665f1b2c9a1e4d0012ab3c40" },
    { "title": "Development",  "amount": 500000, "dueDate": "2026-08-15" },
    { "title": "Deployment",   "amount": 200000 }
  ]
}
```

## How funds release

<Steps>
  <Step title="Fund in full">
    The buyer funds the entire escrow once via
    [Pay escrow](/api-reference/payments/pay-escrow-buy). State becomes `OPENED`.
  </Step>

  <Step title="Confirm each milestone">
    For each completed milestone the buyer calls
    [Confirm milestone](/api-reference/milestone-escrow/confirm-milestone). That
    milestone's amount is released to the **seller's** main balance and its
    `status` becomes `RELEASED`. If the milestone was created with a
    **`customerId`**, the funds go to that **customer's** main balance instead.
  </Step>

  <Step title="Auto-complete">
    When the **final** milestone is released, the escrow automatically moves to
    `state: CLOSED` / `status: COMPLETED`.
  </Step>
</Steps>

<Info>
  You can read the milestone list at any time (including for standard escrows,
  which simply return an empty array) via
  [Get milestones](/api-reference/milestone-escrow/get-milestones).
</Info>

<Note>
  **Milestone escrows cannot be disputed.** Because funds release
  milestone-by-milestone as the buyer confirms each one, there is no single held
  amount to contest; [dispute resolution](/concepts/dispute-resolution) applies to
  standard escrows only.
</Note>