The ‘Unfinished Feature’ Trap: What to Do When a Client Demands a Full Refund Over One Bug

I once mentored a brilliant frontend developer named David. He spent four months building a complex inventory management system for a mid-sized logistics company.

The software was beautiful. It was fast. The client even quietly started using it in their live warehouse operations to track incoming shipments.

But then, the final invoice for $14,000 came due. Suddenly, the client stopped answering calls. When they finally replied, they pointed to a single, obscure bug.

If a user rapidly double-clicked the “archive” button on a legacy browser, the page would freeze for two seconds.

Because of this two-second delay, the client claimed the entire system was “unusable.” They refused to pay the final invoice.

Worse, they officially demanded their initial deposit back. They wanted a full refund.

David called me in a complete panic. He was ready to give the money back just to make the nightmare stop.

This is where freelancers quietly get destroyed.

You aren’t dealing with a technical issue anymore. You are dealing with a business negotiation disguised as a quality assurance problem.

Knowing what to do when a client demands a full refund over a minor defect is the difference between surviving as a business owner and folding.

Let’s break down exactly how to handle this calmly, legally, and professionally.

---

The Perfectionist Blockade

Look, software is never completely finished. It is only abandoned or maintained.

Clients know this. Or at least, the smart ones do.

When a client suddenly becomes a hyper-perfectionist right before the final payment, they are usually running a specific playbook.

I call it the Perfectionist Blockade. It is a financial strategy, not a technical one.

They use a minor flaw to freeze your final payment. They hope you will panic.

They assume you don’t understand contract law. They expect you to offer endless free revisions just to keep them happy.

Often, they will quietly keep using your work while refusing to pay for it.

If you suspect this is happening, you need to This is often discussed under scenarios involving when a client uses your work but refuses to pay you.

Do not let them move the goalposts. You did not sell them a flawless, bug-free enterprise system with a ten-year warranty.

You sold them a custom software build. Custom software has bugs. That is reality.

Your goal right now is to separate the emotional threat of a refund from the factual reality of the code you delivered.

---

Defining ‘Substantial Performance’ in Software

Here’s the thing : you don’t need to be perfect to get paid. You just need to be substantially complete.

This isn’t just my opinion. It is a deeply established legal doctrine.

In contract law, there is a concept called “Substantial Performance.”

It means that if you have delivered the primary value of the contract, the client cannot cancel the whole deal over a minor defect.

Imagine hiring a contractor to build a house. They finish the entire house, but they install the wrong color doorknob on the bathroom door.

You cannot legally refuse to pay for the house. You also cannot demand a full refund.

In similar disputes, courts often avoid denying payment entirely if the core work has been delivered, instead adjusting for defects where applicable , minus the cost of fixing that one specific doorknob.

The same logic applies to your software, your designs, or your marketing campaigns.

If the core application functions as intended, you have substantially performed your duties.

In the United States, commercial contracts are often viewed through the lens of the Uniform Commercial Code (UCC).

While the UCC has a “perfect tender rule” for physical goods, services and custom software lean heavily on substantial performance precedents.

According to the Restatement (Second) of Contracts § 237, minor defects typically do not discharge payment obligations — although how this is applied depends heavily on the facts of each case.

In the UK, the Consumer Rights Act 2015 states that digital content must be of “satisfactory quality.”

Satisfactory does not mean flawless. It means fit for the general purpose it was designed for.

If you agreed to terms via messages, you might be wondering about your legal standing.

You should check if a WhatsApp chat can count as a legally binding contract in your jurisdiction. Often, it absolutely does.

So, when they scream for a refund, take a breath. In many jurisdictions, contract law often recognizes the value of work already delivered, especially under doctrines like substantial performance.

---

How freelancers typically evaluate bug severity when payment is disputed

To remove the emotion from this dispute, I use a framework.

I call it the How freelancers typically evaluate bug severity when payment is disputed. It systematically tears down their QA complaints against their payment obligations.

When a client sends me a list of complaints, I categorize every single item using this exact logic.

High Severity (Showstoppers)

• Definition : The system crashes. Data is actively lost or corrupted. Core functions are completely inaccessible.
• Payment Rule : The client is justified in holding the final payment.
• Action : High-severity issues typically require immediate prioritization to preserve client trust and contractual goodwill. at no extra cost.

Medium Severity (Workarounds Exist)

• Definition : A feature is broken, but there is an alternative way to accomplish the task. Or, a secondary feature is non-functional.
• Payment Rule : Pro-rated hold. They should release 80-90% of the funds, holding a small retainer until the fix is deployed.
• Action : Negotiate a partial release of funds, then schedule the fix.

Low Severity (Cosmetic & Edge Cases)

• Definition: UI misalignments. Bugs that require five specific, weird clicks to trigger. Typos.
• Payment Rule: Full release of funds required immediately.
• Action: Invoice must be paid in full. These bugs are pushed to a post-launch maintenance queue.

If your client is demanding a full refund over a “Low Severity” bug, This type of dispute sometimes arises when expectations and deliverables are interpreted differently by both parties.

You must call out this behavior professionally but firmly.

---

The Bug Logging Protocol

When a client wants to trap you, they will send vague complaints.

They will email things like, “The system is glitchy,” or “It just doesn’t feel right.”

This is a nightmare scenario. You cannot fix “glitchy.”

You need to establish a strict Bug Logging Protocol. This is how you take back control of the conversation.

Stop accepting vague emails. Stop taking phone calls where they just vent about the software.

Force them into a structured process. Make them prove the defect exists.

Tell them that for any bug to be considered valid, it must be submitted with exact reproduction steps.

I require a specific device name, browser version, expected result, and actual result.

A simple screen recording using a tool like Loom works wonders here.

If they refuse to provide this information, you can safely assume the bug isn’t that serious.

Often, asking for this level of detail makes the “refund” threat disappear entirely.

They realize you are treating this like an engineering problem, not a customer service panic.

If they just go silent and stop responding to your protocol, you need to change tactics.

Learn how to handle it when a client ghosts you after you send the invoice. Silence is just another delay tactic.

---

Forcing Conditional Handover Settlements

Let’s say the bug is real, but it’s clearly a minor issue. They still refuse to pay until it’s fixed.

You are worried that if you fix it, they will just find another bug. Then another.

This is how scope creep slowly bankrupts freelancers.

You need to set boundaries. Read up on how to stop working for free and prevent scope creep to protect your profit margins.

The solution here is the Conditional Handover Settlement.

You agree to fix the bug, but you tie the deployment of that fix directly to the clearance of their payment.

You do not upload the fix to their live server. You upload it to your staging server.

You let them test it there. Once they verify it works, you hold the code.

You politely inform them that the final source code and deployment will be executed within two hours of the final invoice clearing your bank account.

This removes their leverage. They can see the fix exists, but they can’t take it and run.

If they start playing accounting games at this stage, don’t just wait around.

You might be stuck in a corporate delay loop. Try using a psychological trick to get paid fast when a client delays.

---

HTML Tool : The Conditional Settlement Email Generator

When you are stressed, you might write an emotional email. Do not do that.

You need to sound like a detached, highly professional agency.

Use this HTML tool mockup as a template for your communications.

Copy this exactly. It is polite, objective, and completely locks down your position.

It tells them: “I did the work. You can see the work. Now pay me.”

---

Avoiding the “Subcontractor Trap”

Sometimes, the person demanding the refund isn’t the end client. It’s a middleman agency.

They might be withholding your pay because their client found a bug.

This is incredibly common, and it is incredibly frustrating.

Your contract is with the middleman, not the end user. Their cash flow problems are not your software problems.

If the agency tries to pass their financial risk onto you, you have to push back hard.

In some specific cases, you might have leverage you don’t realize.

Check out the rules on whether an unpaid subcontractor can sue the end-client directly. It’s complex, but vital to know.

---

Evidence Checklist : Build Your Paper Trail

If this dispute escalates, whoever has the best documentation wins. Period.

Before you send a single demanding email, gather your evidence quietly.

If you walk into a dispute without these items, you are highly vulnerable.

• The Original Scope of Work (SOW) : Does the document explicitly state the software must be “bug-free” for payment? It likely doesn’t.
• Milestone Approvals : Did they pay for Phase 1 and Phase 2? That shows a pattern of acceptance.
• Usage Logs : Do you have analytics showing they are actively using the “broken” software in the real world? This is a massive legal advantage.
• The “Looks Great” Emails : Find any message where they praised the work before this current dispute started. Save it to a PDF.

Once you have this evidence, you operate from a position of power.

You aren’t a freelancer begging for cash. You are a business enforcing a commercial agreement.

If they still refuse to pay, you might need to apply a bit of financial pressure.

Look into whether you can legally charge interest on late freelance invoices to show them delays have consequences.

---

How to think about your next move in a payment dispute

You need to calculate the actual risk of fighting this versus walking away.

Use this matrix to figure out your next step.

High Risk Scenario

• Condition : You have no written contract, the bug actively breaks their business, and they have paid you nothing yet.
• Action : Apologize. Fix the bug immediately. Do whatever it takes to salvage the relationship and get some cash in the door.

Medium Risk Scenario

• Condition : You have a decent contract. They paid the deposit. The bug is annoying but not fatal.
• Action : Use the Conditional Handover Protocol. Stand your ground, but be willing to hop on a quick call to de-escalate.

Low Risk Scenario

• Condition : You have an ironclad contract. The bug is entirely cosmetic. They are actively using the software to make money.
• Action : Deny the refund request entirely. Send a formal demand letter for the final payment.

If you are in that Low Risk category, don’t let them intimidate you.

You can escalate this yourself. Read up on how to recover an unpaid invoice without hiring a lawyer.

---

United States vs. Global: The Regulatory Reality

I talk to freelancers all over the map. A common myth is that if you cross a border, all legal rules go out the window. They don’t.

Commercial contract law shares the same basic DNA almost everywhere.

Let’s start with the United States.

If a client tries to withhold your $10,000 final payment over a minor CSS glitch, the law usually protects you. It comes down to a concept called “Substantial Performance.”

You don’t have to take my word for it. The Legal Information Institute at Cornell Law School breaks this doctrine down clearly. If you delivered the core value of the contract, the client has to pay you, minus the cost of fixing that one minor defect.

Software contracts in the US often blur the line between “goods” and “services.” But even under the Uniform Commercial Code (UCC), courts look for good faith. They fundamentally reject the idea of unjust enrichment.

Now, what if you are a freelancer working out of India, dealing with US clients ? Or a US agency hiring talent overseas?

While contract law differs across jurisdictions, many common-law systems share similar principles, such as partial performance and unjust enrichment doctrines.

In India

the Indian Contract Act, 1872 governs these commercial relationships. Section 39 essentially prevents a client from canceling a contract if you have already performed the core promise.

If a client in New York tries to void a massive software build from a developer in Bengaluru over a trivial bug, Indian contract principles, particularly under doctrines like quantum meruit, may also support compensation for work already performed depending on facts.

And if they try to keep your code without paying ? Indian law allows you to claim “quantum meruit” under Section 70 of the Act. This literally translates to “what one has earned.”

The courts consistently uphold this. You get paid for the work actually done.

Here is the real problem, though. The challenge isn’t the law itself. It’s the enforcement across borders.

Suing a client internationally is a logistical and financial nightmare. A judgment in Mumbai doesn’t easily empty a bank account in Delaware.

This is exactly why you cannot rely on the court system to save you.

Setting up your payment structures correctly from day one is your only real defense. It takes the power out of the client’s hands.

You should carefully consider which payment terms (Net 15 vs. Net 30 vs. Net 45) protect your cash flow best.

Getting paid in smaller, more frequent milestones eliminates the risk of a massive standoff at the finish line. Don’t leave your profit margin sitting in the final invoice.

Of course, outcomes depend heavily on contract wording, jurisdiction, and evidence quality.

---

Quick Decision Flow : What to Do Right Now

If you are reading this while staring at an angry email demanding a refund, follow this logic flow.

Having a structured approach can help reduce reactive decision-making in such situations.

If you have completed your end of the flow and they still won’t budge, you need a timeline.

You can’t wait forever. Use an exact follow-up timeline for late invoices that actually works.

---

Knowing When to Walk Away

Sometimes, despite doing everything right, a client goes nuclear.

They threaten lawsuits. They threaten to ruin your reputation online.

I want to be perfectly clear: 99% of the time, this is a bluff.

Lawyers are incredibly expensive. No rational business owner is going to spend $10,000 in legal fees to sue a freelancer over a $3,000 invoice dispute.

They rely on the threat of legal action to bully you into submission.

However, you must know your own breaking point.

If the final invoice is for $500, and the client is causing you severe mental distress, sometimes the smartest business decision is to walk away.

You don’t refund them the deposit, but you let the final payment go. You revoke their server access, pack up your code, and move on.

But if the invoice is for $15,000? You fight.

You hold the line. You use the tools and the laws I’ve outlined above.

If you decide to fight, you need to know exactly when it is officially time for a freelancer to take legal action.

Don’t guess. Follow a structured escalation path.

---

FAQs About Refund Demands

---

Final Thoughts

I know exactly how your stomach drops when that email comes in.

You doubt your own skills. You wonder if you actually did a bad job.

Stop doing that.

Professional software has bugs. Multi-billion dollar tech companies push bugs into production every single day.

Your client is trying to hold you to an impossible standard to protect their cash flow.

Stand your ground. Be polite, be clinical, and point to the contract.

You are a business owner. It is time to start acting like one.

---

About Author

Adv. Sagar Haribhau Shirsat is an active legal professional specializing in commercial transaction architectures, cross-border corporate compliance, and digital debt recovery systems. He designs strategic asset-protection and recovery frameworks that help freelancers, independent contractors, and global agencies defend their cash flow and enforce their billing rights.

Connect via his Official Professional LinkedIn Profile.

---

Disclaimer : This guide is intended for educational purposes and risk management analysis. It does not replace formal legal counsel. For specific cross-jurisdictional contract disputes, always consult a certified attorney or local legal advocate.