Marketplace ledger with double-entry guarantees
Every balance change is a double-entry write. Invariants enforced at the database, monitored by cron, and provable to auditors.
Answers the question
How do I add a double-entry ledger to my marketplace?
Summary
A marketplace ledger is the source of truth for who is owed what. Soledgic's ledger enforces the standard double-entry invariant (`SUM(debits) = SUM(credits)`) at the database, monitors the invariant continuously, and makes the trail queryable. The atomic posting helpers (`record_sale_atomic`, `process_payout_atomic`, `record_refund_atomic_v2`, `void_transaction_atomic`) are the sanctioned write path; direct entry writes are blocked at CI time.
Primitives in play
- transactions + entries tables
Standard double-entry schema. Every balance change is a transaction; every transaction has two or more entries.
- Atomic posting helpers
One RPC per money-moving operation. CI gate blocks direct entry writes outside these helpers.
- ledger_invariant_cron
Continuously verifies invariants (assets = liabilities + equity, sum-of-entries balance) on production data.
- Closed-period enforcement
Once a period is closed, ledger writes for that period are rejected. No retroactive edits.
How it fits together
- Create your ledger. One ledger per environment (sandbox + live). All accounts and transactions belong to it.
- Let Soledgic provision accounts. Cash, creator_balance, platform_revenue, processing_fees, tax_withholding accounts are created lazily on first use.
- Always go through the atomic helpers. Never INSERT into `entries` directly. The CI gate enforces this.
- Query balances in real time. `get_balance` returns the current available balance for any account.
Code
Inspect a creator balance
const { balance } = await soledgic.balances.get({
accountType: 'creator_balance',
entityId: 'creator_maya',
})
// balance is the SUM of all (credit − debit) entries on that account.Post a corrective transfer
await soledgic.transfers.create({
fromAccountType: 'platform_revenue',
toAccountType: 'creator_balance',
toEntityId: 'creator_maya',
amount: 500, // $5.00
referenceId: 'adjust_2026_05_15',
description: 'Goodwill credit for delayed payout',
})When it fits
- Marketplaces, creator platforms, app economies — anywhere multiple parties hold balances on your books.
- Use cases that need audit-quality bookkeeping (SOC-2, financial reporting).
- Platforms that have been bitten by reconciliation bugs and want the schema to prevent them.
FAQ
Can I export balances to my own data warehouse?
Yes. The ledger is queryable via the SDK and the OpenAPI surface. Most platforms snapshot balances nightly into BigQuery/Snowflake for analytics; the production source-of-truth stays in Soledgic.
How are refunds modeled?
A refund posts a `record_refund_atomic_v2` transaction that reverses the original sale's creator and platform entries proportionally. The original sale stays as `completed`; the refund is a separate transaction linked back via `reverses`.
Try it in sandbox
Sandbox keys are issued instantly. The full flow runs end-to-end against simulated rails — no real money required.