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. Layer handles this with a loan opening balance: the portion of the loan’s outstanding principal that its recorded history does not explain. 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. You do not compute it. Layer derives it, anchored on the date the business activated on Layer, because that is when its books begin.

​
Send the loan’s whole history

If you can send every proceed and payment back to the loan’s origination, do that and send no balance at all.
  • If none of that history predates the business’s activation date, the recorded events explain the loan on their own and there is no opening balance.
  • If some of it does, Layer rolls that part up into an opening balance dated at the activation date. Events on or after activation post normally on top of it.
Either way you send the same thing: everything you have, in whatever order it arrives. For long payment histories, use the bulk payments endpoint to send them in batches rather than one request per payment.

​
When you cannot reach the start of the loan

If your data begins partway through the loan’s life, pass reported_balance when you create or update the loan, and send every event from that point on.
Request
Set at to the earliest date you can state the balance for, not the most recent. It marks where your knowledge of the loan begins, and events dated before it are rejected, so an at that is later than necessary shuts out history you could otherwise record.
  • If at is on or before the business’s activation date, Layer rolls the balance forward through any events between the two and dates the opening balance at activation.
  • If at is after activation, the opening balance is dated at at.
  • at cannot precede the loan’s origination_date, and it cannot postdate history already recorded on the loan.

​
Recording earlier history later

If you later obtain records from before your current at, re-send reported_balance with the earlier date and the balance as of that date, then send the events. The assertion is the boundary, so the boundary has to move before the earlier events will be accepted. Once your history reaches the loan’s origination, retract the assertion by sending reported_balance as null on an update, and let the recorded events speak for themselves. Simply omitting reported_balance does not retract it, and neither does re-sending the loan through POST /loans. After a retraction, Layer re-derives the opening balance from the loan’s recorded history alone: if the history predating the activation date leaves principal outstanding, an opening balance remains, now dated at activation; if the loan was already repaid by then, none does. Loan responses include the active opening_balance, so you can always read back what Layer currently derives.