Skip to main content
Sometimes a loan enters Layer mid-life: the business took the financing before joining your platform, or your integration discovers the loan only when a repayment appears. In those cases you usually don’t have the full history of proceeds and payments, so recording only what you have would leave the loan’s balance overstated, and the loan would never show as fully repaid. Layer solves this with a loan opening balance: the portion of the loan’s outstanding principal that is not explained by recorded proceeds and payments. It is journaled against Opening Balance Equity, so it puts the debt on the books without fabricating a cash disbursement, and repayments recorded from then on walk the balance down to zero. Rather than computing the opening balance yourself, pass reported_balance when you create or update the loan: the outstanding principal at any point in time. Layer derives the opening balance from your assertion and the proceeds and payments already recorded on the loan.
Request
Here the business was advanced $20,000.00 in March, but $8,000.00 of principal had already been repaid before the loan entered Layer. Reporting the $12,000.00 balance as of June 1 creates a $12,000.00 opening balance; there is no need to reconstruct the earlier repayments. The derivation works with whatever history you have recorded:
  • If recorded proceeds and payments fully explain the reported balance, no opening balance is created (and any existing one is cleared).
  • If the derivation would be negative (recorded proceeds exceed the reported balance plus the principal already recorded as repaid), the request fails with a 400. This is a built-in consistency check on your data.
  • Re-sending reported_balance after backfilling more history re-derives the opening balance. Because creating a loan with an existing external_id upserts it, syncs can include the assertion on every run.
Set at to a time you actually know the balance for: typically the moment your reliable data begins, such as just before the first repayment you will record. Avoid backdating into periods whose books are already closed: prior statements were delivered without this loan, and an entry dated inside them restates those books.

​
Alternative: set the opening balance directly

If you have already computed the outstanding principal net of everything you plan to record, set opening_balance explicitly instead. It is mutually exclusive with reported_balance.
Request
On update, omitting opening_balance leaves it unchanged, and passing null explicitly removes it (the ledger entry is reversed). The balance must be positive, and effective_at must be on or before every recorded proceed and payment on the loan. Proceed and payment dates are evaluated as midnight US Eastern time at the start of their date, so an opening balance effective at exactly that instant counts as on or before a same-day event. Loan responses include the active opening_balance, so you can always read back what is currently set.

​
Recording history the opening balance already includes

The opening balance marks where the loan’s recorded history begins, so proceeds and payments dated before its effective_at are rejected: recording them would double-count activity the opening balance already reflects. An event counts as before the opening balance only when midnight US Eastern time at the start of its date is strictly earlier than effective_at; a same-instant event is treated as on or after it and records normally. If you later obtain real historical records (for example, paydowns from before the loan entered Layer, or the original disbursement), record them with included_in_opening_balance: true. Layer backs each event out of the opening balance (a payment’s principal portion increases it, a proceed’s amount decreases it) and moves the opening balance’s effective_at back to the event date, so the explicit record replaces what the opening balance implied and the loan’s balance is unchanged. Continuing the example above, backfilling one of the pre-Layer repayments raises the opening balance from $12,000.00 to $13,000.00, while the payment itself brings the balance right back down (the MCA’s derived split puts $1,000.00 to principal and $150.00 to fee):
Request
Once every pre-Layer repayment and the original $20,000.00 disbursement have been backfilled this way, the opening balance reaches zero and is cleared: the loan is then explained end-to-end by explicit history. Backfill flagged events newest-first, since each one must predate the opening balance’s current effective_at. If you have events in arbitrary order, record the later ones normally and re-send reported_balance afterwards to re-derive the opening balance.