Skip to main content
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:
At least 2 milestones are required.
Every milestone amount must be a positive integer.
The sum of milestone amounts must equal the escrow amount.
whoPays must be buyer — the buyer always covers the Payluk fee on milestone escrows.
The customer-id header is required, identifying the customer the escrow is created on behalf of.
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 below). Unlike standard escrows, milestone creation uses a JSON body (no file upload). 
{
  "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

1

Fund in full

The buyer funds the entire escrow once via Pay escrow. State becomes OPENED.
2

Confirm each milestone

For each completed milestone the buyer calls 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.
3

Auto-complete

When the final milestone is released, the escrow automatically moves to state: CLOSED / status: COMPLETED.
You can read the milestone list at any time — including for standard escrows, which simply return an empty array — via Get milestones.
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 applies to standard escrows only.