tomgranot/hubspot-admin-skills/lifecycle-progression-workflow

Lifecycle Stage Progression Workflow

Automate the contact journey through the sales funnel with four progression workflows, each triggered by a specific business event.

Progression Paths

Prerequisites

• HubSpot Marketing Professional or Enterprise plan
• A HubSpot service key (HUBSPOT_ACCESS_TOKEN in .env; an existing legacy private app token also works) with the automation scope (for the API path)
• Python 3.10+ with `uv`
• Lead scoring model configured (run /build-lead-scoring first) — you need the internal name of your score property
• Deal pipeline set up with a "Closed Won" stage
• Meeting tool or integration configured (for SQL transition)

Scripts

Script paths are relative to this skill's directory. Run them from your project directory so .env, data/, and reports/ resolve there: prefix each path with wherever this skill is installed (skills/lifecycle-progression-workflow/ in a clone of the repo).

before.py inventories existing workflows and checks name collisions. execute.py creates all four progression workflows via POST /automation/v4/flows — always disabled, for review before enabling. after.py verifies and reports enabled state.

Building the Workflow: Two Options

Option A: Create via the v4 Automation API (primary)

API status: HubSpot documents the Workflows API as beta and subject to change. Its current reference is the date-based beta path /automation/v4/2027-03-beta/flows; this skill's scripts still call the unversioned /automation/v4/flows path, which v4's end of support on March 30, 2027 also covers. Creating workflows disabled and reviewing them in the UI is what makes a beta API acceptable here. If a script's create call starts failing, the manual UI build below is the fallback.

All four progression workflows are linear (filter-based AND trigger → set lifecycle stage), which the v4 API expresses directly. The script encodes:

The last workflow uses hs_current_customer — the read-only system property HubSpot introduced in June 2026 that marks contacts belonging to a current customer — as a cleaner signal than inspecting associated deal stages.

Before running: set LEAD_SCORE_PROPERTY in execute.py to your score property's internal name. With HubSpot's post-2025 lead scoring tool, each score you create generates its own property — find the internal name under Settings > Properties (it is not the retired hubspotscore).

uv run scripts/before.py
uv run scripts/execute.py

Safety model: all four workflows are created with isEnabled: false. Review the triggers in the UI, add the optional internal-notification actions (marketing team, sales owner, CS/onboarding — recipients are portal-specific), then enable them one at a time, watching the first enrollments.

Option B: Manual UI Build

Follow the step-by-step instructions in Stage 3 below. Use this on portals where the Automation API is unavailable, or when you prefer to configure the meeting/deal triggers with portal-specific event conditions instead of the property-based equivalents the script uses.

Alternatives: HubSpot Breeze AI can scaffold these workflows from prompts, but it creates event-based (OR) triggers where AND logic between the event and the current stage is required, and cannot configure re-enrollment — verify everything it builds. The Claude Chrome extension can drive the workflow builder UI directly. Both are secondary options.

Step-by-Step Build Instructions

Stage 1: Plan

1. Define your MQL score threshold (typically 40-60 on a 0-100 scale). Adjust after 30-60 days of observation.
2. Identify your lead score property's internal name (post-2025 scoring tool properties are per-score; see /build-lead-scoring).
3. Confirm your deal pipeline stages include a clear "Closed Won" equivalent.

Stage 2: Before

1. Run uv run scripts/before.py to inventory workflows and check name collisions.
2. Document current lifecycle stage distribution (run the audit or check the property breakdown) so you can measure the impact.

Stage 3: Execute

Option A: run uv run scripts/execute.py, then complete the UI review steps listed above.

Option B — manual UI build: build each as a separate contact-based workflow.

Workflow 1: Lead to MQL

1. Trigger: Your lead score property is greater than or equal to [threshold] AND lifecycle stage is "Lead"
2. Action: Set lifecycle stage to "Marketing Qualified Lead"
3. Action (optional): Send internal notification to marketing team
4. Re-enrollment: OFF

Workflow 2: MQL to SQL

1. Trigger: Meeting booked (use "Meeting activity date" is known, or "Number of meetings booked" is greater than 0) AND lifecycle stage is "Marketing Qualified Lead"
2. Action: Set lifecycle stage to "Sales Qualified Lead"
3. Action (optional): Send internal notification to sales owner
4. Re-enrollment: OFF

Workflow 3: SQL to Opportunity

1. Trigger: Associated deal is created (use "Number of associated deals" is greater than 0) AND lifecycle stage is "Sales Qualified Lead"
2. Action: Set lifecycle stage to "Opportunity"
3. Re-enrollment: OFF

Workflow 4: Opportunity to Customer

1. Trigger: Associated deal stage equals "Closed Won" AND lifecycle stage is "Opportunity"
2. Action: Set lifecycle stage to "Customer"
3. Action (optional): Send internal notification to CS/onboarding team
4. Re-enrollment: OFF

Workflow Settings (all four)

• Re-enrollment: OFF (lifecycle should only progress forward)
• Suppression list: None needed — the lifecycle stage condition prevents backwards movement
• Time zone: Not applicable

Stage 4: After

1. Run uv run scripts/after.py (API path) to confirm all four workflows exist and report enabled state.
2. Test each workflow with a test contact:

• Manually adjust score/create meeting/create deal/close deal and confirm progression.

1. Verify that workflows do not conflict — a contact should not be enrolled in two progression workflows simultaneously.
2. Check that lifecycle stages only move forward (HubSpot enforces this by default, but verify).
3. After one week, review the workflow history for each. Check for:

• Contacts stuck at a stage despite meeting criteria
• Unexpected enrollment volumes

Rollback

1. Turn off any or all four workflows.
2. Lifecycle stages already set remain — HubSpot does not allow backward movement without manual override or a dedicated reset workflow.
3. If stages were set incorrectly, create a temporary workflow or use the API to reset affected contacts.

Notes

• Backward movement: HubSpot prevents lifecycle stage from going backward by default. If a deal is lost and the contact should return to MQL, you need a separate "regression" workflow that explicitly sets the stage.
• Multiple deals: If a contact has multiple deals, the Opportunity-to-Customer workflow fires when any associated deal is closed-won. This is usually the desired behavior.
• Score decay: HubSpot's post-2025 scoring tool supports engagement decay, so a contact's score may drop below the MQL threshold after promotion. This is fine — the lifecycle stage is already set and will not regress.