Guides
Start typing to search…

Ledger Based Portal Guide

📘

Before You Begin

  • Review the API reference for the /portal_info endpoint: (See here).

  • Ensure your portal is classified as a "Ledger-Based" portal.
    Not sure? Check the Determine Your Portal Type section.

❓What This Guide Covers

This guide explains how Ledger-Based portals should populate the request body for the /portal_info endpoint,
with a focus on fields that require detailed explanations.

Guide Structure:

  • leaseObject Overview – Overview of key fields in the lease object, including key considerations.
  • Example Ledger Breakdown – See how fields are derived from a sample ledger.
  • Full Request Payload – A complete JSON example of a properly formatted request.

👁️ lease Object Overview

This section highlights key fields in the lease object that require additional explanations.
A live example will be provided later, demonstrating how these fields are derived from a sample ledger.

📘

Check API Reference for Full Schema

This overview explains specific fields but does not include the full API schema.
To review the complete schema, see the API Reference.


🔘 lease.open_balance Field:

The tenant’s outstanding balance for the lease, in cents.
This is the default amount shown to the tenant when they access the portal.


🔘 lease.payments_enabled Field:

Whether the tenant can make payments to the lease.
Pass true or false based on whether payments can be made for the lease.

⚠️ This field directly determines if Livble can push rent for the lease.


🔘 lease.autopay_amount_in_cents Field:

If the tenant is enrolled in automatic payments within your portal, what is the monthly payment amount?

  • If autopay is set for a fixed amount each month, pass that amount.
  • If autopay is enabled but the exact amount is unknown, pass 1.
  • If the tenant is not enrolled in autopay, pass null.
  • 📖Read More Here

🔘 lease.partial_payments_allowed Field:

Indicates whether the tenant can make partial payments.

  • If the tenant can pay an arbitrary amount, pass true.
  • If the tenant must always pay the full open_balance, pass false.

🔘 lease.historical_payments Field:

The payments made by the tenant for the lease.

Send all payments made by the tenant.
If the history is too long, send payments from the last 12 months.

⚠️ Payment amounts should always be positive.


🔘 lease.charges Field:

A list of all charges associated with the lease, including past, current, and future charges.


⚠️ Important Note:
Please send all charges that were added to the ledger, including:

  • Security deposit charges.
  • Fully paid historical charges.
  • Future charges (even if not yet added to open_balance).
  • And as a general note, don't exclude any charge.

📥 Nested Fields:

  • charge.has_been_applied_to_open_balance → Indicates if the charge was ever added to the ledger's open_balance.

  • charge.original_amount_in_cents → The charge's full amount in cents (The amount added to ledger for this charge)

  • charge.amount_paid_in_cents → The amount paid by the tenant for this specific charge.

    • Always passnull for this field.
    • This is because in Ledger-Based portals, payments are not tied to specific charges.

💳 Modeling Credit Charges:
Set a negative value for original_amount_in_cents to model credit charges.


📓 Example Ledger Breakdown

Now that we've covered the relevant fields,
this section will demonstrate how those fields should be derived from an existing ledger.

Below is a sample ledger modeled after typical Ledger-Based portals.
🖱 Click on any ledger item to see how it maps to the /portal_info request payload.

📘

The following ledger is a static snapshot from: February 5th 2025

How it looks in /portal_info body:

lease.open_balance = 105000

Balance Breakdown:

Applied Charges:
2025-01-01 Rent
+ 1000.00$
2025-02-01 Rent
+ 1000.00$
2025-02-02 Landlord One Time Discount
- 50.00$
2025-02-04 Utility Charges
+ 100.00$
Total Applied Charges:
+ 2050.00$

Historical Payments:
2025-01-03 Card Payment
+ $1,000.00
Total Historical Payments:
+ $1,000.00

Open Balance:
Total Applied Charges
+ $2,050.00
Total Historical Payments
- $1,000.00
Total Open Balance
+ $1,050.00


Note: In this example, the rent charge from 2025-03-01 is a future charge, and it was not applied to the open balance.

How it looks in /portal_info body:

lease.charges[0] = {
   // The unique ID of the charge in your system.
   "id": "charge-id-0",
   // The due date of the charge.
   "due_date": "2025-01-01 00:00:00",
   // The charge description in your system.
   "description": "Rent",
   // The charge amount in cents.
   "original_amount_in_cents": 100000,
   // For ledger based portals, this field is always null.
   "amount_paid_in_cents": null,
   // Because this is a past/present charge, it means it was applied to the open balance.
   "has_been_applied_to_open_balance": true
}

How it looks in /portal_info body:

lease.charges[1] = {
   // The unique ID of the charge in your system.
   "id": "charge-id-1",
   // The due date of the charge.
   "due_date": "2025-02-01 00:00:00",
   // The charge description in your system.
   "description": "Rent",
   // The charge amount in cents.
   "original_amount_in_cents": 100000,
   // For ledger based portals, this field is always null.
   "amount_paid_in_cents": null,
   // Because this is a past/present charge, it means it was applied to the open balance.
   "has_been_applied_to_open_balance": true
}

How it looks in /portal_info body:

lease.charges[2] = {
   // The unique ID of the charge in your system.
   "id": "charge-id-2",
   // The due date of the charge.
   "due_date": "2025-02-02 00:00:00",
   // The charge description in your system.
   "description": "Landlord One Time Discount",
   // The charge amount in cents.
   "original_amount_in_cents": -5000,
   // For ledger based portals, this field is always null.
   "amount_paid_in_cents": null,
   // Because this is a past/present charge, it means it was applied to the open balance.
   "has_been_applied_to_open_balance": true
}

How it looks in /portal_info body:

lease.charges[3] = {
   // The unique ID of the charge in your system.
   "id": "charge-id-3",
   // The due date of the charge.
   "due_date": "2025-02-04 00:00:00",
   // The charge description in your system.
   "description": "Utility Charges",
   // The charge amount in cents.
   "original_amount_in_cents": 10000,
   // For ledger based portals, this field is always null.
   "amount_paid_in_cents": null,
   // Because this is a past/present charge, it means it was applied to the open balance.
   "has_been_applied_to_open_balance": true
}

How it looks in /portal_info body:

lease.charges[4] = {
   // The unique ID of the charge in your system.
   "id": "charge-id-4",
   // The due date of the charge.
   "due_date": "2025-03-01 00:00:00",
   // The charge description in your system.
   "description": "Rent",
   // The charge amount in cents.
   "original_amount_in_cents": 100050,
   // For ledger based portals, this field is always null.
   "amount_paid_in_cents": null,
   // Because this is an upcoming charge, it means it was not applied to the open balance.
   "has_been_applied_to_open_balance": false
}

How it looks in /portal_info body:

      
lease.historical_payments[0] = {
   // The unique ID of the payment in your system.
   "id": "historical-payment-id-0",
   // The date the payment was made.
   "payment_date": "2025-03-01 00:00:00",
   // The amount paid in cents.
   "amount_in_cents": 100000,
   // The payment method used.
   "payment_method": "CreditCard",
   // The status of the payment.
   "payment_status": "completed",
}

1/1/2025

Rent

$1,000.00
$1,000.00

1/3/2025

Card Payment

( $1,000.00 )
$0.00

2/1/2025

Rent

$1,000.00
$1,000.00

2/2/2025

Landlord One Time Discount

( $50.00 )
$950.00

2/4/2025

Utility Charges

$100.00
$1,050.00

Upcoming Charges

3/1/2025

Rent

$1,000.50
$1,000.50

📦 Full Request Payload

Below you can find an example for a full /portal_info request payload.
The data in the request matches the information from the example ledger shown above.

Updated 10 months ago