Multi-Vendor Marketplace Payouts: The Ledger States Founders Forget

The dangerous marketplace schema is easy to recognise: an order has total_amount, vendor_amount, platform_fee and payout_status. It looks complete until a partial refund arrives after the vendor transfer, a chargeback lands after payout, or one order contains products from three sellers.

The fix is not a longer payout-status enum. It is a separation between commercial events, provider objects and accounting entries.

Separate the order from the money

An order describes what the customer bought. A charge describes an attempt to collect money. A transfer allocates funds to a connected account. A payout moves an account balance to an external bank. These events can occur at different times and can fail independently.

Stripe documents this separation directly: with separate charges and transfers, the platform charge is decoupled from transfers and one payment can fund multiple connected accounts.

Your database should preserve that distinction even if the first provider makes the workflow look simple. Provider IDs belong on integration records; the internal ledger should describe why money moved in business language.

Use immutable ledger entries

Do not update a vendor balance as the only record of a transaction. Append entries and calculate the balance from posted debits and credits. Corrections should be new entries that reference the original event.

• Gross sale credited to the order clearing account.
• Platform commission credited to platform revenue.
• Vendor payable credited to the vendor account.
• Processing fee, tax, tip or delivery allocation recorded separately where applicable.
• Refund, dispute, reserve and manual adjustment recorded as their own events.

This is an application ledger design pattern, not jurisdiction-specific accounting advice. A qualified accountant should decide the chart of accounts, revenue recognition and tax treatment for the operating market.

States founders commonly omit

Pending availability

A successful customer payment may not be available for transfer immediately. Track the provider balance state and the business hold independently.

Partially allocated

A multi-vendor cart may have a valid charge while one seller allocation is blocked by missing verification or a negative balance rule.

Held or reserved

The platform may intentionally delay settlement for returns, service completion or risk review. Store the reason, amount, owner and release condition.

Reversed

A transfer reversal is not the same event as a customer refund. Preserve both relationships so support can explain what happened.

Payout failed

The vendor payable can remain valid even when the bank payout fails. Bank details, payout retry and vendor notification belong to the payout workflow, not the order.

Design refunds before launch

For a partial refund, define how platform fees, delivery fees, tips, tax and vendor proceeds change. Decide whether the platform absorbs processing costs and what happens when the vendor has already been paid.

Stripe notes that in indirect charge models the platform can be responsible for fees and negative balances. Its Connect configuration guidance is a useful reminder that charge type changes liability, data visibility and refund responsibility.

Make webhook processing idempotent

Store the provider event ID before applying a mutation. Use a database uniqueness constraint so the same event cannot post the ledger twice. Process each event transactionally: claim the event, validate its object version, append entries, update the operational projection and mark the event complete.

Do not assume event order. A delayed transfer event can arrive after a payout event, and a retry can arrive after the first delivery already succeeded. Reconciliation must compare internal objects with provider reports rather than trusting delivery sequence.

Give operators an explainable view

• Order timeline: purchase, fulfilment, cancellation and refund decisions.
• Money timeline: charge, fee, transfer, reserve, reversal and payout.
• Current position: customer refund due, vendor payable, platform exposure and unavailable funds.
• Evidence: provider object IDs, webhook IDs, approver, reason and timestamps.

A good admin panel does not allow someone to overwrite the balance. It allows an authorised operator to post a reasoned adjustment with a second review where risk warrants it.

The launch gate

Run tabletop tests before production: full refund before transfer, partial refund after transfer, dispute after payout, failed payout, vendor suspension, multi-vendor cancellation and duplicate webhook. If the ledger cannot reconstruct every outcome without editing history, it is not ready to hold marketplace money.