Key Takeaways
- One buyer’s payment covers several makers, arrives before fulfilment and can be reversed weeks later, which is why the money cannot simply be forwarded and the platform ends up holding it in between.
- A payout is the sum of immutable ledger entries and never a recomputation from orders, because orders change and a payout that changes after it was paid cannot be defended.
- The run will be retried, re-triggered by hand and fired twice by a scheduler, so a payout has to be a claim with a unique identity created before the provider is ever called.
- Holds, reserves and negative balances are ordinary marketplace states, and the difference between a platform makers trust and one they leave is whether each of them is visible with a reason and a date.
- Payouts finish last because they depend on completed orders, but the ledger has to exist from the first completed order, since entries that were never written cannot be reconstructed later.
Payout Design Signals
- Write ledger entries from your first completed order, even if no money moves for a month.
- Create the payout record with its identity before you call the payment provider, never after.
- Show every hold on the statement with a reason in plain language and an expected release date.
- Decide your negative-balance policy now: carry forward, recover a proportion per cycle, or write off with an approver.
- Publish the cut-off rule in the vendor terms, and select by entry timestamp rather than order date.
Real Insights
- The float a marketplace accumulates is a liability rather than working capital, and the system should be able to split the bank balance into money owed, money held and money earned at any moment.
- Provider idempotency keys expire within hours or days, so the uniqueness guarantee has to live in your own database first if a manual recovery three weeks later is not to pay somebody twice.
- A transfer accepted is not a transfer settled, and a payout that lacks separate submitted, settled, failed and returned states will tell a vendor money is coming after the bank has already returned it.
- The statement is the output vendors actually judge, and it is only reconcilable if it carries the transfer reference that will appear on their bank line alongside snapshotted names and rates.
- Miracuves ships a speciality food marketplace where the vendor ledger, scheduled payout runs, holds and statements already exist rather than being discovered incident by incident, and eligible ready-made scopes follow a 6-day deployment path for the build itself.
At two in the morning on a Tuesday, a job wakes up on a schedule nobody is watching. It reads a list of four hundred and twelve approved vendors, works out a number for each, and starts moving money into other people’s bank accounts.
Nothing about that job demos well. It is a loop, some sums and a series of calls to a payment provider. It is also the only subsystem where a defect does not produce a poor experience, but a wrong balance in somebody else’s bank account. The people at the other end are a baker with two staff, a sauce maker who works weekends, a cheesemonger whose rent falls due on the first. When the number is short they notice the same day. When it arrives twice they spend it. When it does not arrive, they stop listing.
This article is about that job: how a multi-vendor speciality food marketplace takes money collected from many buyers and pays it out correctly to many makers, and why the plumbing decides whether the business survives its first refund season.
A marketplace like Goldbelly takes one payment from a buyer and owes several makers out of it.
The Payout Run Inside a Speciality Food Marketplace
The payout run behind a marketplace like Goldbelly is a scheduled job moving real money, with every failure mode that implies.
A disbursement run is a batch process with an unforgiving contract. It selects earnings that have become payable, groups them by vendor, subtracts what the platform is owed and what it is holding, and transfers the remainder.
What the Run Takes In and What It Emits
The inputs are narrow and should stay that way. A time window with a defined boundary. The ledger entries inside it in a payable state. A payout policy per vendor: cadence, hold rules, destination account.
The outputs are a payout record per vendor carrying its own identity and state, a transfer instruction for each positive amount, and a statement a human can read. Everything a vendor later argues about derives from those three artifacts.
A stale search index is recoverable: you reindex. A wrong payout is different in kind, because the money has left. Recovering it means asking a small business to return funds it already treated as income, which is a commercial conversation, not a fix.
Why a Food Marketplace Cannot Simply Forward the Payment
The intuitive design is that the buyer pays, the platform keeps its cut, and the rest passes straight through. Founders reach for it because it appears to delete a subsystem. It does not survive a real basket.
One Payment Covers Several Makers
A basket holds a jar of preserve from one maker, a loaf from a second, cured meat from a third. One authorization, one capture. Three sets of earnings, three commission rates already frozen onto the order, and a delivery line belonging to the platform or to the vendor.
Some providers can split a payment at capture, which is worth using where it fits. But it splits on the numbers you know at that moment, and those are not final. A split at capture is a prediction. A ledger is a record.
Money Arrives Early, Refunds Arrive Late
The gap here is not minutes. A buyer orders on Monday for a Friday slot, and a standing order is charged when it renews and fulfilled days later. Release early and you have released money for an order that may never be made, which is why payable is a state rather than a synonym for paid.
Then the part that ends the forwarding idea. A card dispute can arrive weeks after delivery, and a complaint can land after the vendor has been paid twice. Money in is final, money out is final, and money owed can reverse long after both.
Holding Periods in a Multi-Vendor Food Marketplace
Between capture and transfer, the platform sits on money belonging to somebody else. That period is where this subsystem lives, and how you think about it decides how you build it.
The Float Is a Liability, Not a Balance
A growing marketplace accumulates a bank balance that looks wonderful on a dashboard and is almost entirely other people’s money. An operator who reads it as working capital is borrowing from the roster without saying so.
The engineering consequence is small and important. The system should answer, at any moment, how much of that balance is owed to vendors, how much is held against disputes, and how much is yours. Three numbers, derived from the ledger rather than estimated.
What You Record, and Who Decides the Rule
Whether holding funds for vendors requires a licence, a segregated account or a particular contractual structure depends on where the operator and the vendors are registered. That question belongs to the operator’s own counsel and the relevant authority, not to a software vendor.
What software can do is make whatever rule applies cheap to satisfy: the amount held per vendor, the reason, the date it becomes releasable, and an unbroken history of every movement. A platform that produces that record can meet a requirement. One reconstructing balances from live orders cannot.
Why the Ledger Comes Before the Food Marketplace Payout
If one structural decision here is worth arguing for, it is this. A payout is the sum of ledger entries, never a recomputation from orders.
An Entry Is a Fact, an Order Is a Story
An order changes. It is edited, partially refunded, switched to another fulfilment method, cancelled and reinstated. Its items get renamed and the vendor’s rate gets renegotiated. Living objects are a poor foundation for money.
An entry is the opposite. On this date, for this reason, this vendor’s balance moved by this amount, caused by this order. It carries a reason code, a sign, a reference and a snapshot of whatever mattered at the time. Then it never changes again.
One completed order usually produces several entries: gross earnings for that vendor’s items, a commission deduction at the frozen rate, a delivery line, a co-funded campaign line, and later, possibly, a refund and an adjustment.
Corrections Are New Entries, Never Edits
When an operator finds a deduction was wrong, the temptation is to fix the number. Do not. Write a reversing entry and then a correct one, each with a reason code and whoever caused it.
This is what makes the subsystem defensible. Any balance is the sum of entries up to that point, so a disagreement is settled by reading a list rather than by two people running different queries.
The Run, Stage by Stage
The run itself is short. What makes it safe is that every stage is durable, so a process that dies halfway leaves a state the next attempt can read rather than guess about.
Image Source: AI-generated visual by Miracuves
Freeze the Window, Then Group
The first stage selects entries by their own timestamp and marks them as belonging to this run. Marking matters more than selecting: a second process starting mid-run must not be able to pick up the same entries.
Grouping then produces a candidate payout per vendor, and nothing yet is irreversible. A run that stops here has cost you one cycle, which is the property you want in every stage before the money moves.
Apply Holds, Compute, Then Claim
Holds and reserves are applied as their own entries rather than as an invisible subtraction. A vendor short by the value of a reserve should see a line saying so, not a total that fails to match their arithmetic.
Then the payout is created as a durable record with an identity, an amount, a destination and the state pending. Only then does the run contact the provider. That ordering is the difference between a system that recovers from a crash and one that does not.
Idempotency, Stated Properly
The run will be repeated. Not might be, will be. Treating that as an edge case is how a marketplace pays a week’s earnings twice and hears about it from nobody.
Three Ways a Run Gets Repeated
The first is automatic: a call times out, the client retries, and the original request had already succeeded. The second is human: an operator sees an error in a log and triggers the run again at nine in the morning. The third is infrastructural: a restarted worker, a scheduler firing on two instances, a queue redelivering an unacknowledged message.
The dangerous case is the first, because from inside your process it looks identical to a genuine failure. The transfer succeeded. Your code has no idea.
A Payout Is a Claim With an Identity
Stop treating a payout as an instruction you send and start treating it as a claim in your database with a unique identity. Sending it is an attempt to fulfil that claim. Sending it twice is two attempts at one claim, which is harmless, rather than two payouts, which is not.
That identity should be deterministic and derived from things that cannot change: the vendor, the cycle, the window boundary. A unique constraint enforces it locally and the same string enforces it at the provider. Generate and store it before the call, because a key created afterwards is the one you do not have when the call times out.
What the Provider Guarantees, and What It Does Not
Provider idempotency keys work well but usually expire within hours or days. A re-run three weeks later, which is what manual recovery looks like, falls outside that window and is treated as a fresh instruction. Your own constraint has no expiry, which is why the guarantee lives on your side first, and why a stalled run can recover by asking the provider about a key it already holds.
Holds and Reserves
Holding part of a vendor’s money is not a punishment and should not feel like one. It is how a platform stays solvent against reversals it is liable for. The question is how to hold predictably.
New Vendors, Disputed Orders, Unusual Spikes
A newly approved vendor has no history, so a first payout delayed by a defined number of days, or a small rolling reserve for a few cycles, is ordinary practice. It also covers their first month, when new listings draw complaints because expectation and reality have not met.
A disputed order justifies holding the disputed amount, not the whole payout. Withholding a week’s earnings over one contested jar is a support ticket and, for a maker with thin margins, a cash crisis.
An unusual spike deserves review rather than an automatic hold. A vendor whose volume multiplies overnight was usually featured somewhere or had a good week. Occasionally it is something else. Flag it to a human and set a resolution date.
A Hold With No End Date Is a Missing Payment
Every hold should carry three things the vendor can see: the amount, the reason in plain language, and the expected release date. A hold that appears as an unexplained shortfall is the fastest way to lose a maker with other places to sell.
Publish the rules with the vendor terms, so a maker reads them before their first payout rather than during their first disappointment. The same transparency runs through the vendor spine on the features page, where onboarding, catalogue control and scheduled payouts are one system rather than three.
Negative Balances, the Case Everyone Forgets
Here is the scenario nobody models before launch. A vendor is paid on Friday. The following Wednesday a buyer wins a dispute on an order from two weeks ago, the refund is charged back to the platform, and the vendor’s balance is below zero.
Carry Forward, Recover Gradually, or Write It Off
The default is carry-forward. The balance persists, the next cycle’s earnings offset it, and the vendor is paid the remainder. It needs no machinery beyond the ledger you already have.
Recovering the whole amount from one cycle is permitted and frequently cruel. A vendor expecting a normal week who receives nothing has a cash problem your platform created. Recovering a defined proportion per cycle should be a policy setting, not hard-coded.
Writing it off is a real option and should be an explicit one. Below some threshold the cost of chasing exceeds the debt. Do it with an entry carrying a reason code and an approver, so the money is accounted for rather than quietly forgotten.
The Vendor Who Never Sells Again
Carry-forward assumes future earnings. A seasonal maker who closes after the holidays, a vendor already suspended, or somebody who stopped listing will never generate the entries that clear the balance.
So the balance ages. Track how long it has been outstanding, decide when you ask directly, decide when you stop. The requirement is modest: it must be visible in a report and must never be silently reset to zero by a job that finds it inconvenient.
When a Transfer Fails
Failed transfers are not rare events reserved for bad luck. At four hundred vendors every cycle produces a handful, and the run has to treat them as normal traffic rather than as exceptions.
Image Source: AI-generated visual by Miracuves
The Failure Modes Are Boring and Frequent
An account number with a transposed digit. An account closed since the last cycle. A name that does not match the vendor record closely enough for the receiving bank. A transfer accepted on Monday and returned on Thursday by a bank that took three days.
That last one matters for the state machine. Accepted is not settled. A payout has five states worth distinguishing: pending, submitted, settled, failed and returned. Collapsing submitted and settled into paid is how you tell a vendor money is coming when the bank has already sent it back.
Changing a destination account is a security event with its own verification path, deliberately handled outside this run.
Continue, Surface, and Never Leave It Ambiguous
One vendor’s rejected transfer must not abort the other four hundred and eleven. Each payout runs in its own transaction, and a failure marks that record and moves on. A run that halts on the first error halts at vendor nine and leaves the roster unpaid overnight.
Visibility is the other half. A failed payout needs a state, a provider reason code, a queue somebody actually reads, and a notification telling the vendor what to do. Silence produces the ticket every operator dreads, where the vendor noticed first.
The state you must never allow is the ambiguous one, where a transfer was submitted and your system does not know what happened. It will occur, because timeouts occur. The resolution is to query the provider using the identity you already hold, never to send again and hope, never to mark it failed because it looks stuck. Funds returned later arrive as a new entry.
Where Disbursement Goes Wrong
These failures recur across marketplace builds, each cheap to prevent in week three and expensive to unpick in month nine.
Creating the payout record after calling the provider
The one ordering that cannot survive a timeout. The transfer exists, your database does not know, and the retry sends it again.
Treating a failed transfer as a reason to stop the run
One closed account should not leave the roster unpaid. Isolate each payout in its own transaction and let the loop continue.
Applying holds as an invisible subtraction
A vendor who cannot reconcile their total assumes the platform is skimming. Held amounts belong on the statement as lines with reasons and release dates.
Having no answer for a negative balance
Refunds land after payouts. Without carry-forward, gradual recovery and an explicit write-off path, an operator edits balances by hand, which destroys the audit trail.
Building the statement last
The statement is what the vendor actually receives. Designed at the end, it is a dump of rows nobody can match to a bank line, and every payout question becomes an investigation.
Batching, Cadence and the Cut-Off
Payouts run on a cycle rather than per order, and the reasons are not only technical. Cadence is one of the few settings here that vendors feel directly, which makes it a product decision in an operations costume.
Why Not Simply Pay Per Order
Transfers usually carry a per-transfer cost, so a maker selling twenty small items a day generates twenty charges against a thin margin. Refund exposure is at its maximum, because money leaves as it arrives. Reconciliation becomes noise, and the maker’s bookkeeping becomes a river of tiny credits with nothing summarizing them.
A cycle solves all of it. Earnings net against refunds before money moves, and one transfer produces one statement the maker can hand to whoever does their accounts.
What Cadence Does to Vendor Trust
Makers here are cash businesses with ingredient costs falling due before revenue arrives. Weekly against monthly is not a preference, it is whether a small producer can afford to accept a large order.
Faster cadence is also something you can charge for, and an on-demand payout carrying a fee sits alongside the lines in how the business model works. Offer it deliberately rather than ad hoc to whoever complains loudest, because ad hoc payouts are the ones run manually and paid twice.
What Each Cadence Actually Costs You
| Cadence | What the vendor experiences | What it costs the platform to run |
|---|---|---|
| Per order | Constant credits, no statement, nothing matching a bank feed | Highest fees, maximum refund exposure, unmatched bank lines |
| Weekly, fixed day | Predictable, one statement to file, the default makers expect | Moderate float, one run, a manageable failure queue |
| Fortnightly or monthly | Harder to fund ingredients for a large order | Largest float, slowest feedback on ledger defects |
| On demand, for a fee | Control when it matters, at a cost they accept | A revenue line, plus strict idempotency |
Select by Entry Time, and Publish the Boundary
Every cycle has an edge, and the edge is where arguments happen. The rule that survives is that the run selects by the timestamp of the ledger entry, not of the order. A March order refunded in May lands in a May payout. Reaching back to amend a closed cycle means a statement you already sent no longer matches the one your system prints today.
Then write the boundary into the vendor terms in sentences a person can read. Earnings become payable a set number of days after fulfilment, whatever is payable at the cut-off is paid on the run day, anything later appears next cycle. Almost no payout dispute is about the amount. It is about an order a vendor expected this week.
The Statement Is the Output That Matters
The transfer is what the vendor receives. The statement is what they understand. Teams build the first and postpone the second, then spend a year answering questions the statement would have answered.
What a Reconcilable Statement Contains
Opening balance. Gross earnings itemized by order. Commission deducted at the rate frozen onto each order. Delivery and service lines. Refunds, each naming the order and date, including those from earlier periods. Adjustments with a reason. Holds applied and released, separately. Closing balance. Net transferred.
Then the field most teams omit: the transfer reference that will appear on the vendor’s bank statement. Without it, reconciliation is a guess from amount and date, and the moment two payouts share an amount even that stops working.
The Statement Is Also Your Support Script
Most payout tickets are not disputes. They are a vendor who cannot see why the number is what it is. A statement showing the arithmetic in the order a human would do it turns a conversation into a link.
Keep every issued version immutable and never regenerate an old statement from current data. A statement that changes after issue is worse than none: two versions exist and only one was true. The same principle runs through an operator-owned stack, as in Migrating from SaaS to Owned Infrastructure: A Peak-Hour Performance Comparison.
Reconstructing a Payout Months Later
The test of this subsystem is not whether tonight’s run completes. It is whether, in fourteen months, somebody can take one line from a bank statement and explain every cent without a spreadsheet.
Snapshots Beat Joins to Live Tables
If an entry stores a product identifier and the statement joins to the products table at print time, renaming a product rewrites last year’s statement. If it joins to the vendor’s current rate, a renegotiation changes every statement that vendor ever received.
So the entry carries the values as they stood: the item name, the rate as frozen at settlement upstream, the tax treatment at the time. Storage is cheap and history is not reproducible, an easy trade the first time somebody asks about a payout from two quarters ago.
What a Dispute Actually Asks of You
A vendor disagreement, a card scheme enquiry and an accountant’s question take the same shape. On this date, for this order, what did you pay, what did you deduct, and on what basis.
With snapshotted entries that is a read. Without them it is an investigation involving somebody who remembers the migration. Ask any supplier to regenerate a twelve-month-old statement and compare it to the original, a habit that pays off in The 36-Month TCO Comparison: SaaS Delivery Builders vs. Owned White-Label Engines.
What This Run Does Not Decide
A disbursement run consumes decisions made elsewhere, which is what keeps it testable. It does not set commission rates. The rate arrives already frozen onto each order at settlement and the run only reads it, which is why changing a rate never rewrites a statement already issued.
It does not decide who may be paid, which comes from admission and approval upstream, and it does not choose fulfilment. Here fulfilment is local delivery zones, riders you or your vendors run, or collection in person, chosen per vendor, and the run reads whichever delivery lines that produced. National carrier shipping of perishable goods is a different business with different logistics, and deliberately not what this build does.
Across more than one currency or tax regime, the entry carries the currency and tax treatment recorded at the time, and payouts group by vendor and currency. The wider multi-market structure belongs to the architecture of our food delivery solution rather than to this job.
Where Payouts Sit in the Build Order
Payouts are always the least-finished part of a marketplace on launch day, and the reason is structural. A payout needs completed orders, which need buyers, approved vendors and fulfilment, so the work depending on everything else finishes last.
Scope It First Even Though It Ships Last
The ledger is not the part that ships last. It must exist from the first completed order, because entries never written cannot be reconstructed. Write them from day one even if no money moves for a month.
A defensible launch-day position is a correct ledger, a readable statement, and transfers executed manually while the automated run is finished. That is an operations cost for a few weeks, and it is recoverable. Automated transfers against an incomplete ledger are not. The scope fitting a ready-made deployment window is set out at what the 6-day window actually covers, and the engineering effort on the development cost page.
Four Questions Before You Commit
Ask to see the ledger schema and check the entries are append-only. Ask what happens when the run is triggered twice in five minutes. Ask to see a year-old statement regenerated today. Ask what a negative balance looks like in the vendor’s own dashboard.
A team that has run this answers immediately. One that has not will describe the screens, the distinction drawn in The Out-of-Stock Trap: Why Cheap Delivery Scripts Ruin Restaurant Relationships. The ledger is your evidence and belongs in a database you control, the case for a white label delivery app you own outright, alongside the wider solution catalogue and the team that builds these platforms.
Founder Decision Signals
Speed
The ledger has to be live from your first completed order, not your first payout. Writing entries early costs days. Reconstructing months of history that was never recorded costs weeks and is only partly possible.
Cost
Cadence is a cost lever before it is a courtesy. Per-order transfers multiply fees and reconciliation work; a weekly cycle nets refunds against earnings before money moves.
Scalability
At four hundred vendors a run produces failed transfers every cycle. Design the failure queue, the notifications and the negative-balance path now, because at that volume they are routine.
Market Fit
Makers choose marketplaces partly on how predictably they get paid. Visible holds, a published cut-off and a statement that reconciles are retention features.
Final Thoughts: The Job Nobody Watches Is the One That Decides
Goldbelly’s hardest recurring job is not the checkout. It is paying everyone correctly afterwards.
A marketplace is judged by its buyers on how the food was, and by its makers on whether the money arrived, on the day it was meant to, in the amount they expected, with an explanation they could follow. The second decides whether you have a roster next year.
None of this machinery is glamorous. An append-only ledger, an identified claim, a hold with a release date, a statement that reconciles to a bank line, a failure queue somebody reads on Monday. It pays for itself the first time a run times out halfway through.
If you are scoping this now, the conversation worth having is about your refund window, cadence, hold policy and first negative balance. The approach behind these builds is set out in our food delivery app development service, and if you want to work through the payout design with people who have run it, schedule a consultation and bring your worst payout scenario, because that is the one worth designing for.
FAQs
How do I build an app like Goldbelly with multi-vendor payouts?
Because one payment usually covers several makers, arrives before anything is fulfilled, and can be reversed weeks later by a card dispute. A split at capture uses numbers that are not final yet, and the platform remains liable to the buyer for money it no longer holds. Holding the funds between capture and transfer is not an optional convenience, it is what makes the arrangement work at all.
What does an idempotent payout run mean in a food marketplace?
It means a payout is a claim with a unique identity in your database rather than an instruction you send. The identity is derived from the vendor, the cycle and the window boundary, enforced by a unique constraint locally and passed as the provider’s idempotency key. Generate and store it before the call. A run triggered twice then produces two attempts at one claim, which is harmless, rather than two transfers.
Should a food marketplace payout come from the ledger or the orders?
Because orders keep changing. They are edited, partially refunded, renamed and renegotiated, so recomputing the same week twice produces two different answers and nobody can say which is right. An entry records that on a date, for a reason, a vendor’s balance moved by an amount, then never changes. Corrections are new reversing entries, which means a statement you already issued never silently rewrites itself.
Why does a food marketplace hold part of a vendor payout?
To stay solvent against reversals the platform is liable for. A new vendor with no history may have a first payout delayed or a small rolling reserve for a few cycles, a disputed order justifies holding the disputed amount only, and an unusual spike deserves a human review. Whatever the rule, every hold should carry an amount, a plain-language reason and an expected release date visible to the vendor.
What happens when a refund lands after the vendor has already been paid?
The vendor’s balance goes negative, which is an ordinary state rather than an error. The default is carry-forward, where the next cycle’s earnings offset it. Recovering the whole amount from one cycle is permitted and usually cruel, so recovering a defined proportion per cycle should be a policy setting. If the vendor never sells again, age the balance and write it off with a reason code and an approver.
What should the run do when a bank transfer fails?
Continue. One rejected transfer must not abort the rest of the roster, so each payout runs in its own transaction and a failure marks that record and moves on. The failure then needs a state, a provider reason code, an operations queue and a notification to the vendor. What must never exist is an ambiguous state: query the provider using the identity you already hold rather than sending again.
How often should a marketplace pay its vendors?
On a cycle rather than per order, because per-order transfers multiply fees, maximize refund exposure and produce nothing a vendor can reconcile. Weekly on a fixed day is the default most makers expect, since they are cash businesses with ingredient costs falling due before revenue arrives. Faster access can be offered deliberately as a paid option, which is safer than granting ad hoc payouts to whoever complains loudest.
What has to be on a payout statement for it to be reconcilable?
Opening balance, gross earnings itemized by order, commission at the rate frozen onto each order, delivery lines, refunds naming the order and date including ones from earlier periods, adjustments with reasons, holds applied and released separately, closing balance and the net transferred. Then the field most teams omit: the transfer reference that will appear on the vendor’s bank statement, without which matching is guesswork.
Miracuves is an independent software development company. We are not affiliated with, connected to, sponsored by, or endorsed by any company or product named in this article.
Terms such as “X Clone” are used descriptively. It is how the software industry refers to building a platform with functionality comparable to a known service, and how clients search for it.
The entire design and codebase of our products is built by our own team. Our products contain no code, design, graphics, or content originating from any third-party website or applications.
All third-party names and marks referenced in this article are the property of their respective owners, referenced solely to identify the services discussed.
