Deals in Mapaprop — Complete Guide

PART 1 — User Manual

1. What are Deals?

A deal is the record of a commercial transaction on a property: a reservation, a sale, a rental, a swap, or a fall-through. It is the "what happened, when, with whom and at what price" of every movement of the property.

Concrete example

Your agent María takes a reservation on an apartment for USD 130,000 with a USD 5,000 deposit. A week later, the buyer signs the purchase agreement and the sale closes at USD 128,000 (they negotiated USD 2,000 lower). Mapaprop stores a single deal that went through two states: first Reserved, then Sold. That deal is recorded with: listing price (USD 139,000), buyer's offer (USD 130,000), deposit (USD 5,000), closing price (USD 128,000), buyer, owner, responsible agent, branch, dates. All of that feeds your management reports and your commercial history.

2. What is it for?

Deals exist because, before, Mapaprop only stored the current state of each property (sold, rented, etc.) without context. With Deals you can now:

3. How a deal is composed

Each deal has 4 pieces of information:

3.1 State

Indicates where in the cycle the deal is. It can only be one of these:

⚠️ A closed deal (Sold / Rented / etc.) CANNOT be reverted. If the deal later falls through, you have to create a new deal with the Fallen through state. The closed one remains as history.

3.2 Type

Indicates what type of transaction it is. It is automatically derived from the operation type of the property that is loaded (Sale, Rental, Temporary, Swap).

3.3 Financial data

3.4 Participants

• Seller / Owner: who owned the property (from your contacts list).
• Buyer / Tenant: who did the deal (from your contacts list).
• Responsible agent: the Mapaprop user who opened the deal.
• Branch: the branch the deal belongs to (inherited from the property).

4. Two modes to register a deal: Basic and Business

When you close a deal from a property's record, the "Deal Closing" window opens. There you can choose between 2 ways to register it:

4.1 Basic Mode

• What does it do? It only changes the property's state (Reserved / Sold / Rented / Suspended) and optionally records a closing price.
• What does it NOT do? It does not store contacts, commission, or detailed history. It does not generate a trackable deal in the reports.
• Who uses it? Small agencies that only need to mark the state of their properties without worrying about management reports.
• Required plan: any (Free, Plus, Pro+, Business).

4.2 Business Mode (recommended)

• What does it do? It creates a complete deal with all the data: contacts, offer, deposit, closing, commission, comments. It then appears in all reports.
• Required plan: Business or Business Manager (plans 56 and 57).

4.3 Comparison table

💡 Recommendation: if you have the Business plan, always use Business mode. It is the only way to take advantage of the management reports.

4.4 Decision by plan

5. How to register a deal step by step

5.1 Create a reservation

1. Go to the property's record → "Deal Closing" button.
2. The window opens. Choose "Reserved" among the state options.
3. If you have Business, you go to the step-by-step wizard:
   • State: you already chose Reserved.
   • Operation type (appears only when reserving on your own properties): you choose how the deal is composed — Single side (you represent one party), Double-ended (you bring both seller AND buyer) or Co-brokering (the buyer was brought by another broker from your office or from your network in Mapaprop). In Double-ended and Co-brokering the system creates 2 linked deals (see §7.12). There is also an "External deal" option that takes you to My Deals to register a deal on a property that is not in Mapaprop (see §7.10).
   • Amounts: enter the buyer's offer. If there was a deposit, check the box and enter the amount.
   • Participants: link seller and buyer from your contacts. You can choose one already linked to the property, search for one, or create one on the spot. Any contact you link here is also linked to the property — you will see it later on the record, in the Contacts tab (the seller as Owner, the buyer as Interested).
   • Comments: optional, to leave internal context.
4. Click Save Deal.

The property is marked as Reserved and a red "Deal in progress" chip appears on its record.

5.2 Close the deal (Sold / Rented / etc.)

There are 2 ways to reach the closing:

Option A — From the property's record:

1. Click "Manage Deal" (red button). It takes you to the detail of the reserved deal.
2. There you choose the target state: Close as Sold / Close as Rented / etc.
3. The window asks you for the Closing price and the Commission — both fields are mandatory when closing (the other sections stay collapsed because you already had the data loaded).
4. Click Update Deal.

Option B — From the property's record directly:

1. Click "Deal Closing".
2. Choose the terminal state directly (e.g., Sold).
3. The window opens with the reservation data pre-loaded. You complete closing and commission.
4. Save.

After the closing:

• The deal is left with a terminal state and closing date.
• The property is marked as Sold (or Rented if it was rent / temp / exchange).
• It is recorded in the property's price history.
• It appears in the "My Deals" report of the agent who closed it.

5.3 Cancel a reservation (Fallen through)

When a reservation does not materialize:

1. From the property's record → "Manage Deal" → Fallen through state.
2. Or from the deal detail → red "Cancel reservation" button.
3. Save.

The deal moves to Fallen through (cannot be reverted), the property automatically returns to Available, and it is recorded as a fall-through in the reports (contributes to the agent's "fall-through rate").

5.4 Edit while the deal is in progress

While the deal is Reserved you can correct its data without changing the state. There are two paths:

• From the deal detail (/deals/[id]) → "Edit" button: opens a window to adjust offer and currency, deposit, contacts (seller / buyer) and comments. The commission is not touched here — it is loaded only when closing. This button is for account administrators.
• From the property card → "Manage Deal": the window opens with collapsible sections (State / Amounts / Participants / Comments) to edit what you need.

💡 Previously a reservation could only be edited from "Manage Deal" on the property card. Since 2026-08 there is also an "Edit" button directly on the deal detail, so you don't have to go back to the property.

5.5 Return a property to "Available"

If a property is reserved and the client changed their mind without formalizing a fall-through, you CANNOT send it directly to Available while it has a deal in progress. Mapaprop blocks you with a message:

"There is a reserved deal in progress. To change the property's state you have to resolve it from Manage Deal or mark it as Fallen through."

Two paths:

• Click "Mark as fallen through" from the blocking message → cancels the reservation and frees the property in a single click.
• Click "Manage Deal" → resolve manually (completed closing or fall-through).

This prevents orphaned deals (reserved in the system but the property already put up for sale again).

5.6 Change the state of an already sold/rented property

If the property is sold (deal closed) and you want to put it up for sale again, you can:

1. Mark it as Available from the record (this does NOT affect the closed deal — it stays there as history).
2. Create a new deal when another reservation comes in. The history will show: old deal (sold) + new deal (reserved/closed/fallen through).

6. The 6 deal reports

All accessible from the Panel → Reports menu.

6.1 All deals (/deals)

Complete, filterable listing of all your account's deals.

• Filters: period (from/to), operation type, state, side (seller/buyer — see §7.9), origin (own/external/deleted — see §7.11), branch, agent.
• Mini-cards on top with 12 live KPIs (see §6.7) that respect the applied filters.
• Table with columns: Id (the deal number, e.g. #1234, with a direct link to the detail), Property, Agent / Branch (the responsible agent and their branch), Contact, Type, Side (green badge Seller / purple Buyer / gray Both), Origin (gray badge 🏠 Own / purple 🔗 External / red 🗑️ Deleted), State, Offer, Closing, Commission, Date. A row can also show an alert icon when the deal is part of a linked pair with an anomaly (see §7.12).
• Active filter chips with X to remove individually.
• "+ Add deal" button (admins): creates a manual deal without an associated property (see §7.10).
• Export to CSV for external analysis (respects the filters).
• Mobile: cards instead of a table.
• Who sees it: admins (main / manager). Vendors are automatically redirected to "My Deals".

6.2 My Deals (/deals/my-deals)

The agent's personal dashboard. Designed so each agent can measure their performance.

• Identification of your branch on top (logo or icon + name + address + contact).
• KPIs: open reservations, closings in the period, ARS commissions, USD commissions.
• Rates: closing and fall-through.
• Quick lists: open reservations + latest closings with click to see detail.
• "+ Add deal" button: allows registering a manual deal on an external property (see section 7.10).
• Who sees it: everyone. Vendors see only their own automatically.

6.3 Agency (/deals/business)

Consolidated stats for your agency with agent ranking.

• Identification of your office on top (logo + name + customer data).
• Global KPIs: reservations, closings, commissions, rates.
• Agent ranking: table ordered by closings with volume and closing rate.
• Distribution by operation type: visual bars (sale / rental / etc.).
• Closings per month: temporal evolution table.
• Who sees it: admins (main / manager / adminMain). Vendors do not.

6.4 Network (/deals/network)

Cross-office view for franchise network managers. Only available on the Business Manager plan.

• Aggregated KPIs for the entire network.
• Franchise ranking: table with drill-down (clicking a franchise takes you to its "Agency").
• Who sees it: only customer:manager (Business Manager) + admin:main (Mapaprop support).

6.5 Captures (/deals/captations)

Report of properties approved by moderation and pending in the period.

• Approved captures: how many new properties passed the moderation control.
• Pending: how many are waiting for approval.
• Effectiveness: % of captures that ended in a closing (approximate calculation).
• Closings in the period: for contrast.
• Table: detail by property.
• Who sees it: all roles.

ℹ️ Note on effectiveness: the calculation is approximate — it divides closings in the period over captures in the period without verifying whether the closings actually correspond to the captured properties. It is a guide, not an exact funnel.

6.6 Negotiation Gap (/deals/brecha)

Three key metrics of your negotiation:

• Listing to offer: how much less buyers offer relative to the listed price (on average).
• Offer to closing: how much it adjusts between the initial offer and the closing.
• Total final discount: the gap between listing and closing. It is measured directly (listing against closing), it is not the subtraction of the two previous indicators.
• Average deposit: % of the closing charged as a deposit.

The screen explains it on its own:

• Each indicator shows over how many deals it was calculated.
• A detail by deal lists which deals feed each number (and flags those that do not contribute, for example by having offer and closing in different currencies).
• The "Complete data only" button recalculates the three indicators using only the deals with listing + offer + closing in the same currency → this way the three numbers are on the same group and are indeed comparable to each other.
• Who sees it: admins (main / manager / adminMain). Vendors do not (it is strategic management information). In the agency dashboard there is a direct link "See gap analysis".

6.7 KPI mini-cards (in all reports)

Above each deal listing (/deals, my-deals, branch, network) there is a grid of 12 mini-cards with live metrics. All respect the applied filters (period, branch, etc.). Each card has a tooltip on hover with the exact formula for the calculation.

Row 1 — Volume and counts:

Row 2 — Performance + mix (only appears if there are closed deals):

💡 Row 2 is new (May 2026). If the period has no closings, only row 1 is shown.

7. Important rules

7.1 One reservation per property

Each property can have only one deal in the Reserved state at the same time. If you try to create a second reservation, the system uses the existing one.

7.2 Deals are never deleted

Firm policy. Once a deal is created, it stays in the system forever. Reasons:

• Plan migrations do not affect your history (if you go from Business to Free and back, you recover everything).
• Management reports need long time series.
• Complete commercial auditing.

If you loaded a deal by mistake, you can change it to the Fallen through state with a clarifying comment. There is no physical deletion.

7.3 Terminal states are not reopened

Once a deal moves to Sold / Rented / Fallen through / etc., that state is fixed. If you need to register a new negotiation on the same property, you create a new deal.

7.4 Deleted properties keep their deals

If you delete a property from the system, the associated deals are not deleted. They remain accessible from the global listing with a snapshot of the property's basic data (address, code, zone) but marked as "(deleted)".

7.5 Negotiation gap: always fill in the closing price

For the gap to work well, make sure to always fill in the "Closing price" field when closing a deal (it is mandatory in Business mode). The offer price is optional but recommended.

7.6 A deal in progress blocks changes to the property's state

If a property has an active reservation, you cannot change its state to Available or Suspended without first resolving the reservation (closing it as Sold/Rented/etc. or marking it as Fallen through). The system warns you with a message and offers to mark it as fallen through in a single click.

7.7 Operation type is derived from the property's type

When you create a new deal on a rental property, the deal is born with the "Rental" type automatically. You do not have to choose it. If the property is for sale, it is born as "Sale". This avoids inconsistencies between property type and operation type.

7.8 Every closing is born from a reservation

Rule: you cannot close a deal as Sold / Rented / Swapped / Temporary rental directly on a property that is Available or Suspended. First you have to create a Reservation, and close it from there.

Why: the reservation is the moment where the offer, the deposit (if any), the participants (seller + buyer) and the exchange rate at opening are recorded. Without that info the closed deal is incomplete and traceability for reports is lost (negotiation gap, commissions, captures, etc.).

How it works in the UI:

• In the "Deal Closing" modal on an available or suspended property, the terminal-state cards (Sold / Swapped / etc.) appear disabled in gray.
• You can only click Reserved or Suspended from an available property.
• Once the reservation is created, you go to See Deal (/deals/[id]) and from there you find the "Close as X" button (Sold / Rented / Swapped / Temporary).

Possible exception (under evaluation): temporary rental could allow direct closing in the future because it usually closes quickly without prior negotiation. For now the rule applies universally. This decision is noted in the product roadmap.

If you need to register a closing on a deal that already happened "outside the system" (e.g., you load a historical sale for reports): create the reservation with minimal data (offer = closing price, deposit 0) and then close it as Sold. The process is 2 clicks.

7.9 Seller side vs buyer side (pd_side)

Each deal has a side field (pd_side) that indicates your agency's role in that transaction:

How it is assigned automatically on creation:

• Modal opened from the record of a property in your account (or your agent's) → the deal is born as seller_side.
• Modal opened as a manual deal without a property (external property) → the deal is born as buyer_side.

The user does not need to choose the side: the system infers it from the context. If in the future you need to register both sides, that flow will be available.

Where you see it in the UI: on the /deals/[id] page there is a chip that shows "Seller side", "Buyer side" or "Both sides" depending on the field's value.

Commission per side (implemented 2026-07-30): when a deal has two brokers (a co-brokering) or when the same office brings both sides (direct double-ended pair), the system creates two linked deals — one per side — and each one carries its own commission. The commission is loaded when closing each side (Sold/Rented), never when reserving, and each side is closed separately. In the reports, the pair counts as one deal (the volume is not duplicated), but the two commissions add up. See §7.11.

7.10 Manual deal with an external property

When to use: when the property you are working on is not loaded in your Mapaprop account. For example:

• You take a buyer to see a property from another agency.
• You work in informal co-brokerage with a colleague and want to keep track of the deal.
• You register a historical sale of a property that was never published on your platform.

How to create a manual deal:

The button opens the same deal modal, but in "manual" mode (without a property from the account linked).

💡 You also reach it from a property: if you are registering a deal on one of your properties and in the "Operation type" step you realize that the deal is actually about another property that is not in Mapaprop, choose the "External deal" option. It takes you directly to My Deals, where you register it with the "+ Add deal" button. It exists so that this option is visible and you do not have to know in advance where external deals are loaded.

How the modal looks in manual mode:

• Header: purple 🔗 icon + title "External Deal" + purple badge "Buyer side".
• Purple explanatory banner on top: "Deal on a property that is not in Mapaprop. You are the buyer side..."

What the modal asks for — mandatory fields marked with *:

1. Operation type (4 card-type buttons with icon):
   • 🏷️ Sale
   • 🔑 Rental
   • 📅 Temporary Rental
   • 🔄 Swap

   The labels and order come from the multi-country system (same selector you see when loading a property). If in the future Mapaprop operates in other countries, the labels are translated automatically.

2. Property address (free text input, max 255 characters). Example: "Av. Cabildo 1234, CABA". It serves to identify the deal in listings and reports — without this the deal is left as "No address registered".
3. Branch ⚠️ (mandatory since 2026-05-29 for Admin / Main / Manager): which branch of your agency the deal corresponds to. If you do not choose it, the "Next" button stays disabled. For vendors their branch is assigned automatically and this field does not appear.
4. State (cards): only Reserved and the terminal ones (Sold / Rented / etc. depending on the chosen type) appear. The Available and Suspended cards are hidden: they do not apply to external properties.
5. Offer and amounts: same as a normal deal (offer, deposit/reservation, closing, commission). Remember that when closing (Sold/Rented) the commission is mandatory (see §5.2).
6. Participants: contact selector for Seller/Owner (the counterparty, usually a broker or the direct owner) and Buyer/Tenant (your client). Both optional but recommended for traceability. In external mode the "seller" is loaded as local contacts without being formally linked to a property (there is no property in the system).
7. Comments: free field.

Limitations by role:

Typical use case for the vendor: "I accompanied a buyer to see an apartment from another agency, they got interested, I reserved it informally. I want to keep track so I don't lose the deal." → create a manual Reserved deal from "My Deals". When the deal materializes, let your admin know so they can close it as Sold or Rented.

Tip: if the counterparty is another agency or a colleague broker, you can load that contact with the "Broker" type (see section 8.5) and link it to the deal's Seller field. This way you have traceability of who you worked the co-brokerage with.

7.11 Origin of the deal: Own / External / Co-brokering / Double-ended / Deleted

Each deal has an "Origin" field that classifies it. The Co-brokering and Double-ended origins mark the buyer side of a linked deal (see §7.12). It allows you to filter and understand at a glance what type of deal you are looking at.

Filter by origin: in /deals the "Origin" dropdown has 4 options: All / Own / External / Deleted. Useful for:

• Seeing only the period's manual deals (External origin) and measuring your informal co-brokerage volume.
• Auditing orphaned deals (Deleted origin) and deciding whether to clean them up or keep them.
• Filtering only internal deals (Own origin) for "clean" reports without manual or orphaned ones.

Concrete example:

• You took a buyer to a Remax apartment in March. You loaded a manual deal from "My Deals" → deal with External origin, Buyer side.
• In April you closed a sale of your property code MP007 with a regular buyer → Own origin, Seller side.
• In May you deleted property MP007 from the catalog (you decided not to relist it) → the April deal automatically changes to Deleted origin, but keeps the MP007 code as historical data (snapshot).

💡 The origin is assigned by the system automatically. It is not something you load manually.

7.12 Linked deals: co-brokering and double-ended

Sometimes a deal is not a single one: they are two linked deals, one for each side (the seller and the buyer). It happens in two cases:

• Co-brokering — the buyer was brought by another broker (from your office or your network in Mapaprop). Each office manages and closes its side, with its commission.
• Direct double-ended pair — you (the same office/agent) bring both sides: you represent the seller AND the buyer. Two linked deals are still created, one per side, each with its own commission.

In both cases:

• 2 deals are created in /deals, with a "Co-brokering" (green) or "Double-ended" (blue) badge, joined to each other ("Linked deal" card in the detail).
• The commission of each side is loaded when closing that side (Sold/Rented), never when reserving.
• Each side is closed separately (one can be closed and the other can fall through). The system flags with an alert icon (in the /deals listing and in the /deals/[id] detail) two anomalies of the pair:
  • Different states: one side closed and the other fell through.
  • Different closing prices: both sides closed (Sold / Rented) but with different closing prices. Since it is the same property there should be a single sale price — the commission does differ per side, the closing price does not. The alert warns you so you can review and correct it.
• In the reports, the pair counts as one deal (the volume is not duplicated), but the two commissions add up.

How it is created: when registering a reservation on your property (with Business), the wizard has an "Operation type" step where you choose:

• Double-ended → you bring both sides (seller + buyer). The system automatically creates the 2 linked deals.
• Co-brokering → the buyer was brought by another broker. You choose the counterpart with a cascading selector: office → branch → agent. You can pick a colleague from your own office or from any other office in your network in Mapaprop (closed MLS type networks), with its branch and its agent. The system creates the 2 linked deals.
• Single side → a single deal is registered (capture or single side, without a link).

The commission of each side is loaded when closing that side, never when reserving. (Before, this was chosen with a "It's a co-brokering" checkbox in the state step; since 2026-08 it is a step of its own with the 3 options.)

8. Special cases

8.1 Agent without an assigned branch

If a system vendor does not have an assigned branch, they can access Deals but will see the entire account (the branch filter is not applied). Recommendation: always assign a branch when creating the agent.

8.2 You downgraded from the Business plan to Free/Plus

• Your existing deals are not deleted, they stay in the system.
• You lose access to the deal reports and to Business mode.
• You cannot create new deals (you go back to Basic mode, which only changes the property's state).
• If you return to Business, you recover full access and all your historical deals.

8.3 An agent from one branch looks at a property from another

This is common in networks with multiple branches. The agent:

• Can see the deal history of any property in the account (cross-branch reading).
• Cannot see the detail of deals that are not from their branch (instead they see "🔒 Name of the other branch").
• Cannot create or close deals on properties from other branches.

8.4 Migration of old data without the correct type

If you have deals loaded before April 2026, the "type" field may be set as "Sale" even though the property is a rental (it was a bug). There is a SQL script that recalculates the types of old deals based on the property's type. If you need it applied to your account, contact support.

8.5 Broker contacts (real estate colleagues)

When you create a new contact from the CRM or from the deal modal, there is a "Contact type" selector with two options:

Use cases for the Broker type:

• A partner agency that brings you buyers for your properties (co-brokerage).
• A colleague from another Mapaprop account with whom you share deals from time to time.
• The selling counterparty in a manual deal: the property is theirs, you bring the buyer.

How it appears in the CRM: the "Broker" tag appears automatically in the CRM's label filter alongside the usual tags (Tenant, Owner, Interested, etc.). You can filter all your brokers quickly to see who you have active relationships with.

The Broker tag does not replace the others. If a broker is also a buyer in some deal, they can have both labels (the Broker one assigned when creating the contact, and the Interested one assigned when linking them to a property).

9. Frequently asked questions

Why can't I see the "Business Closing" button? Your plan does not include Deals. You need Business (service 56) or Business Manager (service 57).

Why doesn't an agent see "All deals" in the menu? By design. Vendors see only "My Deals" (their version filtered by their branch and authorship). The global listing is for admins.

Why does a gap indicator give me 0% or no data? Each indicator is calculated only with the deals that have the prices that indicator needs, in the same currency: "Listing to offer" needs listing + offer; "Offer to closing" needs offer + closing; "Final discount" needs listing + closing. If no deal in the period has that data (or it is in different currencies), that indicator is left without a basis. Always load the 3 prices in the same currency so that the deals contribute to all three. The "Complete data only" button shows you only those complete deals.

Can I delete a deal loaded by mistake? No. Change it to the Fallen through state with a clarifying comment. Deals are never deleted.

I mark a property as Sold without Business mode. Do I lose anything? Yes. The change stays on the property (state and closing price) but it does not generate a trackable deal: it does not appear in the reports, does not contribute to the gap, there is no record of buyer/seller. For real management, use Business mode.

Why does the type of my new deals say "Rental" when I create from a rental property? It is the expected behavior: the type is derived from the property's type. Before April 2026 they were all born as "Sale" (bug), now it is inferred correctly.

Can I see deals of properties I already deleted? Yes. In the global listing they appear with a snapshot of the property's data and the note "(deleted)".

When does the automatic "Mark as fallen through" button appear? When you try to change the state of a reserved property to Available or Suspended without closing the deal. The system detects it and offers to resolve it with one click.

What is the "Broker" contact type for? To distinguish your real estate colleagues from your end clients in the CRM. A broker is someone you co-work with, not a buyer or owner. By marking them as a Broker when creating the contact, the "Broker" label is automatically assigned and they appear in the CRM's label filter.

Can I create a deal if the property is not in my account? Yes. It is the manual deal (see section 7.10). You use it when you work as the buyer side on a property from another agency or one that is not published in Mapaprop.

Why does an alert appear on a pair of linked deals? In a co-brokering or double-ended deal, the two deals should close at the same price (it is the same property; what differs per side is the commission, not the closing price). If the two sides closed with different closing prices, or ended up in different states (one closed and the other fell through), the system flags the deal with an alert icon in the listing and in the detail so you can review it.

In a co-brokering, can I choose an agent from another office in my network? Yes. When setting up a co-brokering, the counterpart selector cascades down office → branch → agent and lets you choose either a colleague from your own office or from any other office in your network in Mapaprop (closed MLS type networks). Only public data of the other office is shown (name, branch, agent), never its private information.

PART 2 — Operational Reference (support / account admins)

This part is intended for Mapaprop support, sales, and account admins who need to answer client queries with precision: who can do what, what each plan requires, and how the screens behave according to the role.

For technical details (internal vendor isolation, SQL backfills, edge cases with SQL, commit changelog), see:

• mapaprop-deals-flow.md — code flow and technical edge cases
• mapaprop-deals-changelog.md — history of changes by sprint
• mapaprop-deals-architecture.md — architecture decisions

10. System roles

Mapaprop has 4 access profiles. The "code role" column is only for support that needs to read logs or the internal system.

In this doc, "admin" without a prefix means Main Admin or Network Manager (both roles have management permissions over the account). "Mapaprop Admin" is named explicitly when it applies.

11. Permissions matrix by action

Key rules:

• The agent only opens reservations. They do not close or cancel — those decisions are made by the account admin.
• Deals are never deleted (firm policy — see §7.2). To "void" one, the Fallen through state is used.
• The agent can read the history of any branch but cannot modify deals outside their own.

12. Permissions by screen

/stats/deals hub

The hub cards are gated by role:

The cards appear visually for all plans (including Free), but clicking without Business triggers the upgrade modal.

/deals (All deals)

/deals/my-deals (My Deals)

For the agent, when using "+ Add deal", the branchId is assigned automatically to their branch and the initial state can only be Reserved.

/deals/[id] (Detail of a deal)

"Deals" panel on the property record

The agent reads the history of any property in the account, but only modifies deals from their branch.

"Deal Closing" modal

Which entry points open it and who sees them?

What does the modal show according to plan and role?

Details of the modal's behavior:

• Tags in the header: the modal shows the operation type (Sale/Rental/etc.) and the property type (Apartment/House/etc.) as chips, derived from the property.
• "Reservation offer" + "Reservation amount": when closing an existing reservation, the Amounts section shows these 2 fields (with an amber background) as a reference.
• "Buyer Origin": appears within Amounts when closing a deal. It is optional.
• "Close as X" opens directly in Amounts: when entering from a closing button, the State section stays collapsed (the decision is already made) and Amounts opens directly to confirm the closing price.

Hub sub-reports

my-deals and branch have an identification strip on top:

• my-deals: the agent's branch (logo or icon + name + address + contact).
• branch: office / customer (logo + name + data).

13. Required plan

13.1 Complete Deals system

Requires the Business plan (service 56) or Business Manager (service 57).

For Free / Plus / Pro+:

• The "Deal Reports" menu is visible, but on click it triggers the upgrade modal.
• The "Business Closing" button in the deal modal is blocked with an upgrade modal.
• The backend rejects the deals module endpoints.

13.2 Basic mode of the modal

Does not require a plan — available for everyone. It is the only function of the deals module that is free. It only changes the property's state (Reserved / Sold / Rented / Suspended) and optionally records a closing price. It does not generate a trackable deal, does not contribute to reports.

13.3 Why the decision

The Deals system exists mainly for professional commercial management: measure performance, ranking, gap. That justifies the Business plan. Small customers who only need to mark a property as sold have Basic mode.