Developer documentation for the Deals module in the WPResidence real estate CRM – how the pipeline board is built, the drag-and-drop wire-up, the dual-column schema, and the HubSpot sync.
Storage – wp_wpresidence_crm_deals
Deals live in a 33-column custom table. The schema intentionally mirrors legacy column names alongside new planned names to support the in-progress rename without breaking existing queries.
Dual Column Names
| Legacy | New |
|---|---|
| deal_title | title |
| deal_stage | stage |
| deal_status | status |
| deal_probability | probability |
| deal_value | amount (for HubSpot) |
| handler_agent_id | assigned_agent_id |
Both column sets are populated on write; read code may use either.
Additional Columns
description, private_note, next_action, action_due_date, expected_close_date, stage_changed_at, contact_id, listing_id, hubspot_deal_id, created_at, updated_at.
CRUD API – libs/deal-crud.php
| Function | Purpose |
|---|---|
| wpestate_crm_insert_deal($data) | Insert; fires wpestate_crm_after_insert_deal |
| wpestate_crm_get_deal($id) | Fetch one |
| wpestate_crm_get_deals($args) | Filters: user_id, status, deal_stage, deal_group, contact_id, lead_id, handler_agent_id, date range, search |
| wpestate_crm_update_deal($id, $data) | Update; fires wpestate_crm_after_update_deal with stage-change detection |
| wpestate_crm_update_deal_stage($id, $stage) | Single-field stage update used by drag-drop |
| wpestate_crm_delete_deal($id) | Delete |
| wpestate_crm_bulk_delete_deals($ids) | Bulk delete |
| wpestate_crm_get_pipeline_summary() | Returns per-stage count and total_value aggregates |
Auto-Status Logic
When deal_stage changes, status is recalculated:
closed_won → status = 'won' closed_lost → status = 'lost' anything else → status = 'open'
Pipeline Board UI
Template: page-templates/wpestate-crm-dashboard_deals.php. The board renders one column per stage, read from setting crm_deal_stages. Stage colors come from setting crm_deal_stage_colors (index-matched).
Drag-and-Drop (SortableJS)
SortableJS 1.15.6 is conditionally enqueued on the deals page (see wpestate-crm.php line 59 condition). On drop, JS calls the AJAX action wpestate_crm_update_deal_field:
| Property | Value |
|---|---|
| Action | wpestate_crm_update_deal_field |
| Nonce | wpestate_crm_update_deal_field |
| Allowed fields | deal_stage, stage, deal_status, next_action, action_due_date, last_contact_date |
Other AJAX Endpoints
| Action | Nonce |
|---|---|
| wpestate_crm_save_deal | wpestate_crm_save_deal |
| wpestate_crm_delete_deal | wpestate_crm_delete_deal |
| wpestate_crm_get_pipeline | wpestate_crm_get_pipeline |
Templates
- page-templates/wpestate-crm-dashboard_deals.php – pipeline board / list toggle.
- templates/crm_add_deal.php – add/edit form.
- templates/crm_deal_detail.php – detail page.
- templates/dashboard_deal_unit.php – single-deal card.
Default Picklists
- crm_deal_stages – New, Viewing Scheduled, Offer Made, Negotiation, Closed Won, Closed Lost
- crm_deal_stage_colors – #3498db, #f39c12, #9b59b6, #e67e22, #27ae60, #e74c3c
- crm_deal_statuses – Open, Won, Lost
- crm_deal_next_actions – 8 defaults including Call, Email, Meeting, Send Offer
- crm_deal_probabilities – 10, 25, 50, 75, 90, 100
Hooks
- wpestate_crm_after_insert_deal – triggers automations (deal_created), webhooks (deal.created), HubSpot sync.
- wpestate_crm_after_update_deal – detects stage change and fires deal_stage_changed, deal_won, or deal_lost events.
HubSpot Mapping
| CRM | HubSpot |
|---|---|
| deal_title / title | dealname |
| deal_value | amount |
| deal_stage | Resolved via hubspot_stage_map setting |
The HubSpot deal ID is stored on the CRM row as hubspot_deal_id. Contact association uses the HubSpot associations PUT endpoint /crm/v3/objects/deals/{deal_id}/associations/contacts/{contact_id}/deal_to_contact. Full architecture in the HubSpot CRM integration guide.
Pipeline Summary
wpestate_crm_get_pipeline_summary() performs a GROUP BY deal_stage query returning count and SUM(deal_value) per stage. The Stats page consumes this via the stats AJAX endpoint to render the Deals by Pipeline Stage chart.