Commission Ledger Clawback Design: The Engine That Survives

Why Marketplaces Die on the Boring Part

Nearly every creator-payout business that has imploded did it the same way. They paid out money before it was real.

There was a well-known creator-payout crisis a few years back where the platform paid commissions on pending conversions. Creators saw their balances, withdrew the cash, and felt great about it. Then the refunds came in. The upstream networks settled late or short. The float collapsed. The company had paid out real dollars against revenue that evaporated, and there was no way to get it back.

That is not a UI problem. That is a commission ledger clawback design problem.

Here is the thing founders get wrong. They obsess over the marketplace front end. The creator discovery. The dashboards. The brand. All of it matters for growth, but none of it is what kills the company. The thing that kills the company is the ledger underneath, the part nobody on the founding team wanted to build because it is unglamorous and hard.

I am building a marketplace right now that pays out commissions to creators. And the more I work on it, the clearer it becomes: the unsexy commission engine is the actual product. The front end is replaceable. The payout layer is the business.

I have spent the last two years building financial systems, automation pipelines, and ledgers across a dozen domains. Across all of it, the same lesson holds. The money math has to be deterministic, idempotent, and gated by state. Get that wrong and you do not have a bug. You have an insolvency event waiting for its trigger.

I wrote more about the commission engine that decides if a marketplace survives separately. This article is the deeper version: how I actually design the engine so it survives the first wave of refunds and the first net-90 gap.

The Trap: Paying on Pending Commissions

The float you don't see

A conversion fires. The creator sees a number go up. The naive system pays that number out. Done.

Except that revenue is not real yet, and the system has no idea.

Net-90 networks and refund windows

Two things stand between a conversion and money you can actually spend. First, the customer can refund. Depending on your terms and the network, that window is anywhere from 30 to 90 days. Second, the upstream network that actually owes you the money settles on net-60 or net-90 terms. You booked the revenue today. You will not see the cash for two to three months, if you see all of it.

The float trap: refund and net-90 timeline with worked example

So when you pay a creator on a pending conversion, you are paying cash you do not have, against revenue that might never arrive.

Here is the worked example. A customer buys something for $100. Your commission rule pays the creator 30 percent, so $30 goes out. Forty days later, the customer refunds. Now the $100 is gone, and so is the $30 you paid the creator. Plus the processing fees on both the original charge and the payout. You are out roughly $33 on a sale that never happened.

One refund is annoying. Now run it across 5,000 conversions a month with a 6 percent refund rate. That is 300 clawback events, $9,000 to $10,000 in money you already paid out and have to recover or eat. Every single month.

This is the doubt I want every founder to sit with. You are not underestimating the front end. You are underestimating the payout layer. The float is invisible until it is fatal.

Money Only Moves on Locked Status

Pending, locked, paid: the three states

The first design principle solves most of the problem. Every commission lives in a state machine with three states.

Commission state machine: Pending, Locked, Paid

Pending. Earned but not real. The conversion fired, the creator can see it, but the refund window is open and the network has not settled. No money moves.

Locked. Past the refund window and confirmed settled upstream. This commission is now real money you actually have a claim to.

Paid. Money has physically left your account and landed in the creator's.

Money never moves until a commission is locked. That single discipline prevents most of the implosion described above, because you stop paying out cash against revenue that can still vanish.

Holding a reserve against clawback

Locked does not mean zero risk. Edge cases exist: a chargeback that lands after the window, a network that claws back from you on a technicality. So even on locked commissions I hold a reserve. A small percentage of every payout is held back as a buffer against late clawbacks. It is the same float discipline a payment processor uses on a risky merchant.

The state transitions are deterministic. A scheduled job checks refund windows and settlement confirmations, and moves commissions from pending to locked based on dates and facts, not judgment. There is no AI deciding when money is real. The model never touches the math. I wrote about why that separation matters in let the code compute, not the model.

The ledger underneath all of this is double-entry, because anything that moves money has to balance to the penny. Here is how I build a Postgres ledger that cannot be wrong.

Idempotency: The Difference Between a Bug and a Bankruptcy

Webhooks fire twice. This is not an edge case. It is normal. Stripe, your conversion network, your own retry logic, all of them will deliver the same event more than once.

Idempotency: duplicate webhook handling

Retries happen. A batch job crashes halfway through and runs again. A queue redelivers a message because the acknowledgment got lost.

If your commission engine is not idempotent, every one of those duplicates double-credits a creator. You paid twice for one conversion. At ten conversions that is a rounding error. At ten thousand, with payouts on top, that is the company.

Affiliate commission idempotency means a single conversion can be processed any number of times and only ever credit the creator once.

Here is how I build it. Every conversion event carries an external ID from the source system. Before the engine writes anything, it checks whether that external ID has already been processed. If it has, the write is a no-op. The creator's balance does not move. Process the same event a hundred times, the result is identical to processing it once.

The same rule applies to clawbacks and payouts. A clawback with the same reference fires once. A payout with the same idempotency key executes once, even if Stripe Connect retries the request. This is exactly the discipline I covered in atomic, idempotent financial writes.

This is not optional polish. In a system that moves other people's money, idempotency is the wall between a recoverable bug and an unrecoverable hole in your balance sheet.

Commission Rules That Survive Real Business Logic

A real marketplace payout engine cannot run on a single flat rate. The rules have to match how the business actually grows, and every rule exists to protect unit economics, not just to add a feature.

Commission rule models and caps

First-conversion: percentage, flat, tiered

The engine supports percentage rates (30 percent of the sale), flat rates ($15 per conversion regardless of size), and tiered rates. Tiered is the interesting one. A creator who drives 10 conversions a month earns 20 percent. At 50, they hit 25 percent. At 200, 30 percent. The tier rewards volume without overpaying small accounts, and it is computed deterministically from the creator's confirmed conversion count, not estimated.

Recurring: lifetime, fixed-month, first-purchase

Subscription revenue needs its own models. Lifetime pays the creator on every renewal for as long as the customer stays. Fixed-month pays for the first 12 months, then stops. First-purchase-only pays once and never again. Each one changes your lifetime payout liability dramatically, so the choice is a real business decision encoded into the rule, not a default someone forgot to change.

On top of the rate models, two caps protect you from the outliers that wreck the math. A per-customer cap stops a single whale customer from generating runaway commission liability. A per-link cap stops one viral link from blowing your margin in a single weekend. Without caps, your best day can be your worst.

The engine also distinguishes agent versus human attribution. Was the conversion driven by an automated system or an actual person promoting the product? That changes who gets paid, at what rate, and how you audit it later. Encoding the attribution source up front means you are never reverse-engineering where money went six months into a dispute.

Clawback: Reversing Money You Already Promised

This is the hardest part, and it is the core of commission ledger clawback design. When a customer refunds, you have to reverse the commission. How you reverse it depends entirely on what state that commission is in.

Clawing back pending vs paid commissions

If the commission is still pending, the clawback is clean. You void it. The creator never had the money, so nothing leaves their balance, and the pending number simply disappears.

If the commission is already paid, you have a real problem. The cash is gone. So the clawback creates a negative entry that comes out of the creator's next payout, or sits against their balance until it is recovered. The discipline is that you claw back on both cases, and you record both as proper ledger entries so the books always balance.

The outside-window no-claw rule

Here is the nuance that separates a thoughtful engine from a brutal one. If the refund lands after the agreed clawback window, you do not claw back from the creator. You eat it.

Clawback decision tree by state and window

There are two reasons. First, clawing back a stale commission destroys creator trust faster than almost anything else. Imagine getting money deducted for a sale you made four months ago. Creators leave over that. Second, clawing back outside the window is often contractually barred. Your own terms say you will not.

So the outside-window no-claw rule is a business decision encoded directly in deterministic code. The engine checks the refund date against the window, and the path is fixed: inside the window, claw back; outside, absorb. There is no guesswork and no model judgment.

Every clawback path has test coverage. The pending void, the paid recovery, the outside-window absorption, the idempotent reprocessing of a clawback that fires twice. Money-reversing code is exactly the code you cannot afford to discover is wrong in production.

The Ledger Is the Product

I will say it plainly. The marketplace UI is replaceable. You can rebuild the front end in a month. The ledger you cannot.

The thing that determines whether the business survives its first wave of refunds and its first net-90 settlement gap is the commission engine nobody on the founding team wanted to build. It is idempotent, so duplicates never double-pay. It is state-gated, so money never moves on revenue that is not real. It is clawback-disciplined, so refunds reverse cleanly and stale ones do not burn your creators. And it holds a reserve, so the late edge cases do not catch you with an empty buffer.

That combination is the float and clawback discipline that separates a durable marketplace from one that joins the list of cautionary creator-payout crises.

I will be honest about what is still hard. Reconciliation against upstream network statements is genuinely painful, because networks report on their own schedule, in their own format, and they do not always agree with what your engine recorded. Dispute edge cases get messy fast, especially when a refund and a chargeback fire on the same transaction. I have good systems for both, but neither is fully solved, and anyone telling you it is solved is selling you something.

Here is the takeaway. If you are building a marketplace, a payout business, or anything that moves other people's money, the payout layer is where I would start, not finish. Build the ledger first. The front end can wait. The float cannot.

If that is the problem you are staring at, let's talk about your payout layer.

Want to explore what AI could do for your business?

Book a free 30-minute strategy call. No pitch deck, no sales team, just a real conversation about your operations and where this kind of system actually fits.

Book a Discovery Call