🤝 Money & Accounts

Rent Agreements

Rent Agreements is where you set up and maintain each contract with a vendor who rents shop space, a stall, or a counter from you — the rent amount, how often it is billed, the lease period, and its current status.

📍 Menu path: Money & Accounts → Rent Agreements

👤 Who uses it: Managers/Owners only (managerOnly nav item)

🏷️ Plan tier: advanced+

Overview

Every agreement is tied to a vendor from your Suppliers list — you cannot create one without first picking a vendor, or picking one auto-fills the vendor name.

Agreements carry the commercial terms (monthly rent, security deposit, billing frequency and day) that the Rent Payments page later uses to generate individual billing periods.

Agreements can be Draft, Active, Suspended or Terminated — only ACTIVE agreements are counted in the Rent Dashboard's "Active Agreements" stat and are eligible for automatic payment generation.

Before You Start

Requires the Rent Management feature on the Advanced plan tier or above, and manager-level access.
The vendor you want to bill must already exist in your Suppliers list — the vendor dropdown is populated from GET /suppliers (first 500).

Step-by-Step Guide

1 Create a new rent agreement

Click Add Agreement in the top-right of the page.
Select a Vendor from the dropdown (required) — the vendor's name is captured automatically.
Optionally fill Shop Number (e.g. "A-12") and Shop Area (sq ft) to identify which space is being rented.
Enter Monthly Rent (required) and, if applicable, Security Deposit.
Choose the Billing Frequency — Monthly, Quarterly or Yearly — and a Billing Day (1–31, required) which is the day of the period that rent is due.
Set the Start Date (required) and, if the agreement has a fixed term, an End Date.
Toggle Auto-renew agreement if the lease should keep going automatically past the end date.
Choose a Status (Draft, Active, Suspended, Terminated) — defaults to Active.
Add any free-text Notes, then click Create to save.

💡 Monthly Rent and Security Deposit accept decimals (step 0.01) and cannot be negative; Billing Day is clamped between 1 and 31.

2 Edit an existing agreement

Click the pencil (edit) icon on any agreement card.
The same form opens pre-filled with that agreement's current values.
Change any field and click Save to update the agreement in place.

3 Delete an agreement

Click the trash icon on an agreement card.
Confirm the browser prompt ("Are you sure you want to delete this rent agreement?").
The agreement is permanently removed from the list once confirmed.

💡 Deleting an agreement does not delete rent payment history already generated against it — check the Rent Payments page before removing an agreement you have billed against.

Every Field & Button, Explained

Field / Button	What it does
`Add Agreement`	Opens a blank creation form as a modal.
`Vendor`	Required dropdown of your Suppliers; selecting one auto-fills the stored vendor name on the agreement.
`Shop Number`	Free-text identifier for the physical space being rented, e.g. "A-12".
`Shop Area (sq ft)`	Optional numeric area of the rented space, accepts decimals.
`Monthly Rent`	Required currency amount — the base rent figure used to compute each billing period.
`Security Deposit`	Optional one-time deposit amount, tracked for reference only.
`Billing Frequency`	How often rent is billed: Monthly, Quarterly, or Yearly.
`Billing Day`	Required day-of-period (1–31) on which rent falls due each cycle.
`Start Date`	Required date the lease/agreement begins.
`End Date`	Optional date the fixed-term lease ends; leave blank for open-ended agreements.
`Auto-renew agreement`	Checkbox — when on, the agreement is treated as continuing automatically past its End Date.
`Status`	Draft (not yet active), Active (green, counted in dashboard stats), Suspended (yellow, temporarily paused), or Terminated (red, ended).
`Notes`	Free-text notes shown on the agreement card beneath its details.
`Edit (pencil icon)`	Opens the same form pre-filled for the selected agreement.
`Delete (trash icon)`	Permanently removes the agreement after a confirmation prompt.

Tips & Best Practices

Set the Billing Day to match the day you actually walk the market collecting rent, so generated payments line up with your real routine.
Use Suspended (rather than deleting) for a vendor who has temporarily vacated but may return — it removes them from active dashboard totals without losing the agreement history.
Record the Security Deposit even though it is not billed, so you have a record of what to refund when the agreement ends.

Troubleshooting & FAQ

The vendor dropdown is empty.

Agreements can only be linked to vendors already in your Suppliers list. Add the vendor under Suppliers/Purchase first, then return here.

I created an agreement but it is not on the Rent Dashboard's Active Agreements count.

Only agreements with Status = Active are counted. Edit the agreement and confirm its status.

Saving the form shows an error instead of closing.

The form surfaces the backend's validation message directly (e.g. missing required field). Check that Vendor, Monthly Rent, Billing Day and Start Date are all filled in.

I do not see the "Add Agreement" button.

Rent Agreements requires manager-level access and the Advanced plan tier — confirm both with your Admin.

🧑‍💻 Developer Notes

Source component(s):

frontend-app/packages/pos-react-lib/src/pages/RentAgreementsPage.jsx

Backend endpoints used:

GET /rent-management/agreements
GET /suppliers
POST /rent-management/agreements
PUT /rent-management/agreements/:id
DELETE /rent-management/agreements/:id

Related tables (db-core repositories):

RentAgreement
Supplier

Redux slices:

scope (selectCurrentScope / getScopeQueryParams)

Feature flag key: rent_management (requires advanced plan tier or above)

Vendors are fetched with limit: 500 and the response shape is normalised across three possible formats (array, data.suppliers, or data.data). Form state fully resets between "Add" and "Edit" via handleOpenModal(agreement) — passing no argument clears the form. Both create and update use the same formData shape posted to different HTTP verbs/URLs.