> ## 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 escrow overview

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

A **milestone escrow** holds the whole amount upfront and releases it **in parts**
as the buyer confirms each milestone, ideal for multi-stage work (design → build
→ deploy). It has `settlementType: MILESTONE` and carries a `milestones[]` array.
See [Milestone escrows](/concepts/milestone-escrows) for the concept and
[fees & settlement](/concepts/fees-and-settlement) for how each release is netted.

<Info>
  Funding still uses the shared [Pay escrow](/api-reference/payments/pay-escrow-buy)
  endpoint (the buyer pays the full amount once). The difference is **creation** and
  **staged release**, both covered here.
</Info>

## Endpoints

| Route                                                                              | Method & path                                                | What it does                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create milestone escrow](/api-reference/milestone-escrow/create-milestone-escrow) | `POST /v1/escrow/milestone/create`                           | Creates the staged escrow. **JSON body** (no file upload). Rules: **≥ 2 milestones**, each a positive integer, the **sum equals `amount`**, and `whoPays` must be **`buyer`**. **`customer-id` = seller.**                                                                                                                                                |
| [Edit milestone escrow](/api-reference/milestone-escrow/edit-milestone-escrow)     | `PUT /v1/escrow/milestone/edit/{paymentToken}`               | Replaces the details and full milestone set. **JSON body.** Same rules as creation. Allowed only while **`AWAITING_PAYMENT`** and only by the **seller that created it**; the fee is recalculated. **`customer-id` = seller.**                                                                                                                            |
| [Convert to milestone](/api-reference/milestone-escrow/convert-to-milestone)       | `PUT /v1/escrow/milestone/convert/{paymentToken}`            | Turns an existing **standard** escrow into a milestone escrow by splitting its amount. **JSON body** (`milestones`, plus an optional new `amount`). Milestone amounts must **sum to the target amount**; `whoPays` becomes **`buyer`**. Allowed only while **`AWAITING_PAYMENT`** and only by the **seller that created it**. **`customer-id` = seller.** |
| [Get milestones](/api-reference/milestone-escrow/get-milestones)                   | `GET /v1/escrow/milestone/{paymentToken}`                    | Returns the milestone list with each milestone's `id`, `amount`, `status` and `releasedAt`. Returns `[]` for standard escrows.                                                                                                                                                                                                                            |
| [Confirm milestone](/api-reference/milestone-escrow/confirm-milestone)             | `POST /v1/escrow/milestone/confirm/{escrowId}/{milestoneId}` | Buyer approves one milestone; its amount is released to the seller, or to the milestone's **`customerId`** main balance, if one was set at creation. **`customer-id` = buyer.** The escrow auto-completes when the **final** milestone is released.                                                                                                       |

## How a milestone escrow flows

<Steps>
  <Step title="Create with milestones (seller)">
    `POST /v1/escrow/milestone/create` with a `milestones[]` array summing to
    `amount`. Each milestone may carry an optional `customerId` to route its
    release to a specific customer.
  </Step>

  <Step title="Fund in full (buyer)">
    [Pay escrow](/api-reference/payments/pay-escrow-buy) once → `OPENED`.
  </Step>

  <Step title="Confirm milestone-by-milestone (buyer)">
    Each `POST …/milestone/confirm/{escrowId}/{milestoneId}` releases that
    milestone's amount to the seller (or to its `customerId`, if set) and sets
    its `status` to `RELEASED`.
  </Step>

  <Step title="Auto-complete">
    Releasing the last milestone closes the escrow as `COMPLETED`; no separate
    confirm-payment call.
  </Step>
</Steps>