HubSpot will block in-use pipeline deletes by default in the 2026-09 API version
HubSpot will block Pipelines API deletes of in-use pipelines and stages by default in the 2026-09 API version, announced on July 21, 2026. Integrations moving to 2026-09 will receive validation errors on delete unless they explicitly opt out or remove the underlying references first, as detailed in a developer changelog post and a companion community update.
2026-09 Pipelines API will block in-use deletes by default
HubSpot is aligning API behavior with the product UI by adding a default reference check to pipeline and stage deletions in the 2026-09 date-based API version. In the developer changelog describing the change, HubSpot explains that if a pipeline or stage is referenced by existing records, the delete request will be blocked and return a validation error. A matching community announcement by Dennis Edson confirms the behavior, the 2026-09 scope, and the affected endpoints.
“validateReferencesBeforeDelete” parameter and expected errors
The Pipelines API has long supported an optional `validateReferencesBeforeDelete` parameter. With 2026-09, that parameter now defaults to `true`, so delete calls check for references automatically. To preserve the old behavior, you must pass `validateReferencesBeforeDelete=false` in your delete request. The API guide for pipelines shows how the parameter works and the shape of the `VALIDATION_ERROR` response when a stage or pipeline is still in use. In practice, CI jobs or cleanup scripts that remove pipelines as part of test runs will start failing with 400-level validation errors unless they update requests or clear dependent records first.
Migration guidance and timeline for HubSpot integrations
HubSpot’s update applies only when you adopt the 2026-09 date-based API version. Teams can remain on earlier versions temporarily, but once you migrate, you should either: 1) handle the validation error and prompt users to remove references before retrying, or 2) set `validateReferencesBeforeDelete=false` where a forced delete is intentional and safe. The developer changelog post outlines this migration path clearly, and the community note reiterates that the change does not alter earlier GA versions.
Consistency with HubSpot UI and immediate implications for CRM teams
From an operations standpoint, the update brings the API in line with the HubSpot UI, which already blocks deletion of in-use pipelines and stages. That consistency reduces accidental data loss and makes automated cleanup safer for shared environments. A common issue is orphaned references created by bulk imports or workflow misconfigurations; under 2026-09, those problems surface sooner because delete requests will fail fast with clear validation details. Expect to adjust internal runbooks, developer tooling, and any partner integrations that routinely create and retire pipelines.
Share With Others
Platinum
