settlementType: MILESTONE and carries a milestones[] array.
See Milestone escrows for the concept and
fees & settlement for how each release is netted.
Funding still uses the shared Pay escrow
endpoint (the buyer pays the full amount once). The difference is creation and
staged release, both covered here.
Endpoints
| Route | Method & path | What it does |
|---|---|---|
| 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 | 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. |
| 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 | 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
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.Fund in full (buyer)
Pay escrow once →
OPENED.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.