home / skills / abdullahbeam / nexus-design-abdullah / hubspot-update-deal

hubspot-update-deal skill

safe

/00-system/skills/hubspot/hubspot-update-deal

This skill updates HubSpot deals by ID, allowing stage, amount, name, or close date changes to keep records accurate.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-update-deal

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.6 KB

---
name: hubspot-update-deal
description: "Update an existing deal in HubSpot CRM. Load when user says 'update deal', 'edit deal', 'change deal stage', 'move deal', 'close deal'. Requires deal ID."
---

# Update HubSpot Deal

**Specialized skill** for updating deals in HubSpot CRM.

## Pre-Flight Check

Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.

---

## Usage

### Required Parameters
- `--id` - Deal ID (required)

### Optional Parameters (at least one required)
- `--name` - New deal name
- `--amount` - New deal value
- `--stage` - New deal stage
- `--closedate` - New close date (YYYY-MM-DD)

### Examples

**Update stage (move deal):**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/update_deal.py \
  --id 5840795376 \
  --stage "closedwon" \
  --json
```

**Update amount:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/update_deal.py \
  --id 5840795376 \
  --amount 75000 \
  --json
```

**Close deal as won:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/update_deal.py \
  --id 5840795376 \
  --stage "closedwon" \
  --closedate "2025-12-13" \
  --json
```

---

## Common Deal Stages

| Stage ID | Name |
|----------|------|
| appointmentscheduled | Appointment Scheduled |
| qualifiedtobuy | Qualified to Buy |
| presentationscheduled | Presentation Scheduled |
| decisionmakerboughtin | Decision Maker Bought In |
| contractsent | Contract Sent |
| closedwon | Closed Won |
| closedlost | Closed Lost |

---

## Finding Deal ID

If user says "close the Acme deal", first search:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_deals.py --name "Acme" --json
```

Then use the returned ID for the update.

---

## Output Format

```json
{
  "id": "5840795376",
  "properties": {
    "dealname": "Acme Corp - Enterprise",
    "amount": "75000",
    "dealstage": "closedwon",
    "hs_lastmodifieddate": "2025-12-13T10:30:00Z"
  }
}
```

---

## Display Format

```
✅ Deal updated!
  ID: 5840795376
  Name: Acme Corp - Enterprise
  Updated fields:
    - stage: Closed Won
    - amount: $75,000
```

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.deals.write` scope |
| 404 | Deal not found - check ID |
| 400 | Invalid stage ID |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-search-deals` - Find deal ID
- `hubspot-list-deals` - List all deals
- `hubspot-create-deal` - Create new deal

Overview

This skill updates an existing deal in HubSpot CRM. It performs targeted edits such as changing the deal stage, amount, name, or close date and returns the updated deal record. Designed for quick edits when you know the deal ID. Includes pre-flight config checks and clear success or error responses.

How this skill works

The skill accepts a required deal ID and one or more update fields (name, amount, stage, closedate). It validates configuration, applies the requested property updates to the HubSpot deal, and returns the updated properties in JSON. If a deal ID is not known, run a search first to locate the correct ID before calling this skill.

When to use it

Move a deal to a new stage (e.g., move to Closed Won or Closed Lost).
Update the deal value after a contract change or negotiation.
Change the deal name to match a new contact or account naming convention.
Set or correct the expected close date for forecasting and reports.
Quickly correct property typos or update multiple fields on a single deal.

Best practices

Always run the config check prior to making updates to ensure authentication and scopes are valid.
Provide the deal ID to avoid ambiguity; if you only know the company name, search for the deal first and confirm the ID.
Only send the fields that need changing to minimize unintended updates.
Use valid stage IDs (see common stages) and ISO date format (YYYY-MM-DD) for close dates.
Handle API errors (401, 403, 404, 400, 429) by retrying, fixing scopes, or verifying the ID before repeating the update.

Example use cases

Move deal 5840795376 to the "closedwon" stage and set the close date to 2025-12-13.
Update deal 5840795376 amount to 75000 after a pricing revision.
Rename a deal to match the finalized contract: change dealname to "Acme Corp - Enterprise".
Close a deal as lost by setting dealstage to "closedlost" and adding context in notes.
Batch workflow: search for deals by company, then update the stage for matched IDs.

FAQ

What if I don’t know the deal ID?

Search deals by name first to retrieve the ID, then run the update with that ID.

What date format should I use for close dates?

Use YYYY-MM-DD (ISO) format for close dates to ensure correct parsing.

What if I get a 403 error?

Ensure your OAuth token includes the crm.objects.deals.write scope and reauthorize if necessary.