Paying out to vendors who are owed different amounts

A customer pays once. Behind that single payment sit several independent businesses, each owed a different amount, on a different schedule, in a possibly different currency, minus fees split between them by rules nobody wrote down.

The payment integration is the part everyone estimates. What the ledger says a week later is the part that decides whether the marketplace survives contact with its own vendors.

One payment is not one obligation

The moment an order spans two vendors, the amount collected stops being a useful number.

What matters is the set of obligations it created: this vendor is owed the item price less commission, that one is owed their item less commission plus a shipping contribution, the payment provider takes its fee from the total before anything is allocated, and the platform keeps what remains.

If those obligations are derived on demand from order rows, every later event — a refund, a partial shipment, a fee correction — has to reproduce the same arithmetic, and eventually two places in the codebase disagree about who was owed what. The obligations should be recorded as entries when they arise, not recalculated whenever someone asks.

The general rule: balances are read from a ledger of immutable entries, never stored as mutable totals. A balance that can be written to is a balance that will eventually be wrong with no way to find out when it started being wrong.

Currency has a timestamp

Once money is collected in one currency and paid out in another, the exchange rate is not a detail — it is a decision about who carries the movement between collection and payout.

The rate at the moment of sale, the rate at payout, and the rate the bank actually gives are three different numbers. Whichever is used, the vendor's expectation has to match it, and the difference has to land somewhere explicit rather than quietly reducing the platform's margin and being discovered at year end.

Store amounts in minor units as integers, always with the currency alongside. Never let a converted figure overwrite the original: the original is what was agreed and the conversion is a derived view of it.

Refunds after payout

A customer returns an item three weeks later. The vendor was paid two weeks ago.

The platform now needs the money back from a business that has already spent it. The mechanisms — deducting from the next payout, holding a rolling reserve, invoicing — are all commercial decisions, and the system has to express whichever is chosen rather than assume.

The failure to avoid is a negative payout that the process cannot represent, which is usually discovered when someone runs it and finds the transfer rejected or, worse, sent as a positive amount.

Partial refunds compound this: half an order returned means recalculating commission on the remainder, and whether commission is refunded proportionally is a policy question with a real answer that must be encoded rather than assumed.

Payout is not settlement

An order marked paid is not money in the platform's account. Card settlement takes days, chargebacks arrive later still, and paying a vendor before funds have settled means lending them money.

Most platforms therefore hold funds for a period. That period is a risk decision, and it should be visible to vendors as a stated schedule — because the single most common vendor complaint in this model is not the commission rate. It is not knowing when they will be paid.

The check that catches everything

There is one invariant worth building the system around: the platform's own balance should equal what it has collected minus what it owes and has paid.

Run it on a schedule. When it breaks, it breaks by a specific amount on a specific day, which is nearly always enough to identify the cause. Without it, a discrepancy is discovered by a vendor asking where their money is, and by then it has been compounding for weeks and every figure since is suspect.

This is unglamorous and it is the difference between a marketplace that can explain itself and one that cannot.

Why it is worth the schema

Settlement is the part of a marketplace that is invisible when correct and existential when not. Vendors forgive an ugly interface and a slow admin panel. They do not forgive being paid the wrong amount, and they tell each other.