Ledger Based Portal Guide
Before You Begin
Review the API reference for the
/portal_infoendpoint: (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 theleaseobject, 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
lease Object OverviewThis 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 SchemaThis 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:
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:
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:
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:
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, passfalse.
🔘 lease.historical_payments Field:
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:
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'sopen_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 pass
nullfor this field. - This is because in Ledger-Based portals, payments are not tied to specific charges.
- Always pass
💳 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,050.00
Current Open Balance (Includes past due)1/1/2025
Rent
1/3/2025
Card Payment
2/1/2025
Rent
2/2/2025
Landlord One Time Discount
2/4/2025
Utility Charges
Upcoming Charges
3/1/2025
Rent
📦 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 8 months ago