Milestone Payments for a Freelance Marketplace

Milestone payments in WP Sell Services work like this: a custom project is split into phases, the buyer pays each phase up front, and the vendor’s wallet is credited when the buyer approves that phase’s delivery. Until then the vendor’s share shows as clearing and cannot be withdrawn.

If you came here looking for a plugin that parks the buyer’s money with a third-party escrow service, that’s not what this does, and it’s better to say so now than after you’ve built your terms of service around it. The payment goes through your gateway as normal. What the plugin controls is when the vendor can touch it, and what it gives you is pay-as-you-go: small, sequential payments that cap how much either side has at risk at any one time.

This post explains how a phase moves, who carries the risk at each step, and when you’d skip milestones and sell a single fixed-price order instead.

Pay-per-phase is not the same as holding funds

People use the two ideas interchangeably, and they’re different. In a model where funds are held, the buyer pays the whole amount at the start, the platform keeps it, and the vendor receives it when the buyer approves. Money moves on approval.

In a pay-per-phase model, the buyer pays only for the phase in front of them. That payment goes through at once, and your commission is worked out and locked in for the phase. The vendor’s share is not credited to their wallet yet. When the buyer approves the delivery, the share is credited, minus your commission, and the phase is closed.

Why does it matter? Because the guarantee each side gets is different. A buyer on a held-funds platform has paid in full and is relying on the platform to hand the money back if things go wrong. A buyer on pay-per-phase has paid for one phase and is relying on a vendor who can’t withdraw that money until the work is approved. The exposure is smaller per step, but it isn’t zero.

How a phase moves from proposal to done

Milestones live on orders that start from a buyer request: the buyer posts a brief, vendors reply with proposals, and a vendor can choose a Milestone contract type. They list each phase with a title, a description, an amount and a number of days. The buyer sees the whole plan before accepting, and the order starts with a base price of zero. All of the money flows through the phases.

From there each phase follows the same loop:

1. The buyer pays the phase.
2. The phase moves to In progress, and the vendor’s share is recorded but not yet credited.
3. The vendor does the work and submits a delivery.
4. The buyer approves it, and the vendor is credited then, or sends it back with notes.

Phases run in lock-step. Phase two can’t be paid until phase one has finished, which means approved, declined or cancelled. Paying a phase doesn’t open up the next one. Approving it does. That keeps the project in rhythm and stops a buyer stacking up prepayments for work they haven’t seen. When every phase has been settled and at least one was delivered, the parent order completes by itself.

Vendors can propose extra phases once the project is running, and those have a clock on them. An added phase the buyer hasn’t paid within 48 hours is cancelled automatically. Phases from the original accepted proposal never expire this way. The milestones documentation has every state and error in full.

Who carries the risk at each step

Think about it one phase at a time and it gets clearer.

The buyer has paid for the current phase and hasn’t received it yet. That’s the part to be upfront about with your customers. If the vendor disappears, the buyer’s recourse is a dispute, not an automatic refund.

The vendor can see the buyer has paid before they start, so they know the money exists. They aren’t credited until approval, though, and nothing approves a delivered phase on the buyer’s behalf. A buyer who goes quiet leaves the phase waiting, and the vendor’s only route is a dispute. They also can’t start the next phase until the current one is settled, so they’re never far ahead of what they’ve been paid.

You, the marketplace owner, carry a smaller risk than you might expect but a real one. Once a phase is approved, the earnings are in the vendor’s wallet, so if a refund lands after you’ve paid the vendor out, the reversal becomes a debt that nets against their future earnings. You can soften that with a clearance period in the payout settings, which holds credited earnings (milestone phases included) for a number of days before they can be withdrawn. How long to hold is your call. The plugin doesn’t impose one.

What the vendor’s earnings page shows along the way

A phase passes through four money states, and your vendors will ask about each one.

1. The buyer pays the phase. The vendor’s share appears as clearing: paid for, but not earned yet.
2. The vendor delivers and the buyer approves. The share is credited to the wallet.
3. If you set a clearance period, the credit is held for that many days. The clearance period ships at zero, so by default there is no hold.
4. After clearance, the balance is available, and the vendor can ask for a withdrawal like any other earnings.

Commission is worked out and fixed when the phase is paid, so changing your commission rate halfway through a project doesn’t change what an in-flight phase earns. A phase that is sent back for changes returns to the vendor marked as sent back. The buyer’s notes go on the phase and into the order conversation, and the vendor resubmits.

A worked example: a three-phase website build

These figures are an example only. Say a vendor proposes a website build as three phases, with your commission at ten percent.

The buyer accepts the proposal and pays nothing at that point, because the parent order has a base price of zero. They pay 400 for the first phase. The vendor works, delivers, and the buyer approves. Only then does 360 reach the vendor’s wallet, and only then can the buyer pay for the second phase. When the third phase is approved, the project completes and the buyer gets the usual completion email and the review prompt.

If the buyer had instead sent the first delivery back twice, the vendor would have resubmitted twice, and the phase would still have been a single 400 payment. Revisions on a phase don’t draw on any revision allowance, because a phase doesn’t have one, so the practical limit is the vendor’s patience and the conversation record.

Where the lock-step rule holds, and where it doesn’t

Lock-step is enforced at the places most buyers will actually pay. The pay button on the order page is disabled for a locked phase, the standalone checkout shows a notice instead of a payment form, and the pay endpoints in the REST API refuse a locked phase.

It is not a security control on every route. On WooCommerce the order-pay link for a phase is built without checking whether earlier phases have finished, so a buyer who has the link for a later phase can pay it out of sequence and the payment settles normally. Treat the rule as a way of keeping honest buyers in order. If strict sequencing matters to your terms, run the marketplace on the standalone checkout.

Mistakes that cause milestone disputes

• Phases that are too large. A phase worth most of the project puts you back in the lump-sum position. Split work so that no single approval carries much of the money.
• Vague deliverables in the phase description. The description is what the buyer approves against, and it is also the first thing an admin reads in a dispute.
• No answer to a silent buyer. Nothing approves a delivered phase automatically. Decide what a vendor should do after a week of silence, and publish it.
• Promising protection you don’t provide. Don’t tell buyers their money is held until the end. It isn’t.
• Forgetting the unpaid-phase clock. A phase the vendor adds mid-project is cancelled after 48 hours unpaid. Vendors should add phases when the buyer is ready to pay.

Disputes and refunds

Once a phase is paid, the buyer can’t simply decline it. A paid phase can only be settled through a dispute. Either side opens one, both sides add their evidence, and an admin picks a resolution, which can be a full or partial refund. Read how that works in the dispute process docs.

This is the honest centre of the whole feature. Your admins are the referee. If you’re going to run a marketplace on this model, decide in advance how quickly you’ll respond to disputes and what evidence you’ll expect, and write it into your terms. A buyer who’s paid for phase two and isn’t getting a reply from the vendor wants to know a person is on the other end of the dispute button.

Declined and unpaid phases are simpler. A vendor can cancel a proposed phase the buyer hasn’t paid, and a buyer can decline one. No money has moved, so there’s nothing to reverse.

When a single fixed-price order is better

Milestones are for scoped projects where neither side wants to commit the full amount on day one: a website build, an edited manuscript, a phased consulting engagement. They aren’t the right fit for a one-off logo or a thirty-minute consultation, and they don’t exist on catalog orders at all. For a fixed-price service, extra paid work goes through extensions instead, and the two features never appear on the same order.

If a buyer wants the money protected until the very end of the project, pay-per-phase can’t offer it. Be clear about that in your marketplace’s copy, and don’t borrow language from platforms that work differently.

Choosing between milestones and a fixed price

A quick test helps when a vendor is unsure which contract type to pick on a proposal. If the work has one deliverable and one date, pick fixed price, because a one-phase milestone plan only adds steps. If the work has stages that each deliver something reviewable, pick milestones. For a catalog service where the buyer wants extra work added later, use a paid extension, because the two features never appear on the same order.

The freelance marketplace use case shows these contract types in a full buyer-request setup, and the vendor overview explains what a seller sees on each phase.

A checklist before you offer milestones

Run through this once on a staging copy, using a test buyer and a test vendor.

1. Post a request, send a milestone proposal with two phases, and accept it.
2. Pay the first phase and confirm the vendor’s earnings show as clearing, not available.
3. Deliver, send the phase back once, resubmit, then approve. Confirm the credit lands only after approval.
4. Try to pay the second phase before approving the first, on each checkout you use, and note which routes stop you.
5. Add an extra phase as the vendor, leave it unpaid, and confirm it cancels after the 48 hour window.
6. Open a dispute on a paid phase and walk through the ruling you would actually give.

If any step surprises you, it will surprise a customer too. Fix your terms or settings before launch, not after.

Setting it up

Milestones are part of the free plugin and sit on the buyer-request flow, so the first step is having that flow in use and a vendor ready to reply with a proposal. Phase payments run on the standalone checkout or on WooCommerce, which is a Pro feature. Other checkout platforms aren’t supported for phase payments, so a marketplace on one of them can’t offer milestones or paid extensions.

Then decide three things before you launch. Set your commission rate and any clearance days in Settings. Write down your dispute response time. And tell vendors in your onboarding that approval is what credits a phase to their wallet, so they know why money shows as clearing and what to do if a buyer goes quiet.

If you want the wider picture first, custom WooCommerce flows a service marketplace needs covers milestones alongside the other flows that standard checkout doesn’t. The request marketplace use case shows the buyer-request model end to end, and free vs Pro lists what each tier includes.