/deals

name: "HubSpot Deals"
description: >
  HubSpot deal records and sales pipelines: deal fields, default and custom
  pipeline stages, deal amount conventions (MRR vs. TCV), forecast categories
  and weighted forecasting, and associating deals with contacts and companies.
when_to_use: >-
  When searching, creating, updating, or reporting on deal records and pipelines in HubSpot CRM. Use
  when: hubspot deal, hubspot pipeline, hubspot opportunity, hubspot sale, hubspot revenue, deal
  search hubspot, deal management hubspot, hubspot forecast, hubspot deal stage, sales pipeline
  hubspot, or hubspot close date.

HubSpot Deal & Pipeline Management

Overview

Deals in HubSpot represent sales opportunities -- potential or active revenue from clients. For MSPs, deals track managed services agreements, project engagements, hardware sales, or any revenue opportunity moving through the sales process. Each deal belongs to a pipeline (e.g., "Sales Pipeline" or "Renewals") and progresses through stages (e.g., "Discovery", "Proposal", "Closed Won"). Deals are associated with contacts and companies to provide full context on who is involved and which client the revenue belongs to.

Anti-triggers

• **Building or pricing the quote behind the deal** — a deal records *that* an

opportunity exists and what it is worth; the line items, catalog, and margin live in `salesbuildr-quotes` or `connectwise-cpq-quotes`.

• **Sending the customer something to sign** — use `pandadoc-documents`.
• **Billing a won deal** — moving a deal to Closed Won invoices nobody; use

`xero-invoices` or `qbo-invoices`.

• **Salesbuildr opportunities** — a different vendor's pipeline object with

identical vocabulary; use `salesbuildr-opportunities`.

MCP Tools

Available Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | `hubspot_retrieve_deal` | Get a single deal by ID | `dealId` (required) | | `hubspot_create_deal` | Create a new deal | `dealname` (required), `amount`, `dealstage`, `pipeline` | | `hubspot_update_deal` | Update an existing deal | `dealId` (required), property fields to update | | `hubspot_list_deal_properties` | List all available deal properties | None | | `hubspot_search_deals` | Search deals by criteria | `filterGroups`, `sorts`, `limit`, `after` |

Search Deals

Call `hubspot_search_deals` with filter groups to find deals:

**Search by deal name:**

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "dealname",
          "operator": "CONTAINS_TOKEN",
          "value": "Managed Services"
        }
      ]
    }
  ],
  "limit": 100
}

**Search by deal stage:**

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "dealstage",
          "operator": "EQ",
          "value": "proposalpendinng"
        }
      ]
    }
  ],
  "sorts": [
    {
      "propertyName": "amount",
      "direction": "DESCENDING"
    }
  ],
  "limit": 100
}

**Search by close date range (upcoming closings):**

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "closedate",
          "operator": "GTE",
          "value": "2026-02-01"
        },
        {
          "propertyName": "closedate",
          "operator": "LTE",
          "value": "2026-03-31"
        }
      ]
    }
  ],
  "limit": 100
}

**Search for high-value open deals:**

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "amount",
          "operator": "GT",
          "value": "10000"
        },
        {
          "propertyName": "dealstage",
          "operator": "NOT_IN",
          "values": ["closedwon", "closedlost"]
        }
      ]
    }
  ],
  "sorts": [
    {
      "propertyName": "amount",
      "direction": "DESCENDING"
    }
  ],
  "limit": 100
}

Create a Deal

Call `hubspot_create_deal` with the deal's properties:

**Example: Create a managed services deal:**

• `dealname`: `Acme Corp - Managed IT Services`
• `amount`: `5000`
• `dealstage`: `appointmentscheduled`
• `pipeline`: `default`
• `closedate`: `2026-04-15`
• `hubspot_owner_id`: `67890`

Update a Deal

Call `hubspot_update_deal` with the `dealId` and the properties to change:

**Example: Move deal to next stage:**

• `dealId`: `54321`
• `dealstage`: `proposalpending`
• `amount`: `6000`

Retrieve a Deal

Call `hubspot_retrieve_deal` with the `dealId`:

**Example:**

• `hubspot_retrieve_deal` with `dealId=54321`

Key Concepts

Default Pipeline Stages

HubSpot's default sales pipeline includes these stages (your account may have custom stages):

| Stage ID | Display Name | Probability | MSP Context | |----------|-------------|-------------|-------------| | `appointmentscheduled` | Appointment Scheduled | 20% | Discovery call booked | | `qualifiedtobuy` | Qualified to Buy | 40% | Budget and authority confirmed | | `presentationscheduled` | Presentation Scheduled | 60% | Demo or proposal meeting set | | `decisionmakerboughtin` | Decision Maker Bought-In | 80% | Key stakeholder agrees | | `contractsent` | Contract Sent | 90% | MSA or SOW sent for signature | | `closedwon` | Closed Won | 100% | Deal signed, revenue booked | | `closedlost` | Closed Lost | 0% | Deal did not close |

Multiple Pipelines

HubSpot supports multiple pipelines for different deal types. Common MSP pipelines:

| Pipeline | Use Case | |----------|----------| | Sales Pipeline | New client acquisition | | Renewals | Annual contract renewals | | Projects | One-time project engagements | | Hardware | Hardware procurement deals |

Deal Amount

The `amount` field represents the deal's monetary value. For MSPs:

• **Monthly recurring deals** - Set amount to the monthly recurring revenue (MRR)
• **Annual contracts** - Set amount to the total contract value (TCV)
• **One-time projects** - Set amount to the project fee
• Be consistent within each pipeline to enable accurate forecasting

##