Ledger Based Portal Guide
Before You Begin
Review the API reference for the
/portal_infoendpoint: (See here).Review the
leaseobject overview: (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:
- Sample Ledger Breakdown – See how fields are derived from a sample ledger.
- Key Notes – Notes on how to populate the request body that are specific to Ledger Based portals
- Full Request Payload – A complete JSON example of a properly formatted request.
📓 Sample Ledger Breakdown
This section will demonstrate how the /portal_info request fields should be derived from an existing ledger.
We will go over some key points that are specific to Ledger Based portals that are demonstrated in this example.
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
🔑 Key Notes
In this section, we cover key considerations for Ledger-Based portals when structuring the /portal_info request.
💡charge.has_been_applied_to_open_balance
charge.has_been_applied_to_open_balanceThis field indicates whether the charge was ever added to the ledger's open_balance:
- If it was ever added to the open balance -> pass
true - If it was never added to the open balance -> pass
fal
📌 Example in the Sample Ledger:
All charges in the Sample Ledger were applied to the open balance, except the upcoming charge.
Click on any charge in the example to see how this field is populated.
💡 lease.open_balance
lease.open_balanceThe tenant's current open balance for the lease in cents.
🧮 How It's Calculated in the Sample Ledger:
In the Sample Ledger, this value is calculated like so: SUM(applied_charges) – SUM(historical_payments)
Click on the open balance in the Sample Ledger above to see a detailed breakdown.
⚠️ Ensure Consistency with Your Portal:
Even if your calculation differs from the Sample Ledger example,
this value must always match the number the tenant sees in your portal.
💡 charge.amount_paid_in_cents
charge.amount_paid_in_centsThis field represents the amount paid specifically for this charge.
However, in Ledger Based portals, payments are not attributed to specific charges.
⚠️Make sure to always passnull for this field. (not 0)
📌 Example in the Sample Ledger:
In the Sample Ledger above, you can see that nullis always passed.
💡 Modeling Credit Charges:
In order to model credit charges for the tenant,
set a negative value for the charge's original_amount_in_cents field.
📌 Example in the Sample Ledger:
In the Sample Ledger above, the "Landlord One Time Discount" is a credit charge.
Click on it to see how it is populated in the /portal_info request payload.
📦 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 5 months ago