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 is naira with at most two decimal places (₦100.20 is 100.2), at least 1.
The sum of milestone amounts must equal the escrow amount (minimum 1000).
whoPays must be buyer: the buyer always covers the Payluk fee on milestone escrows.
maxDelivery (1 to 365) and deliveryTimeline are required, as on a standard escrow.
A milestone’s dueDate, when given, must be a future date.
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).

​
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.
Disputes cover what is still held. The buyer can open a dispute on a milestone escrow as long as at least one milestone is still PENDING; released milestones are already paid and cannot be contested. Once every milestone has been released the call fails with All milestones have been released; there are no held funds to dispute. When you resolve such a dispute, the held milestones are marked REFUNDED or SPLIT to match your ruling.