HubSpot Developer Changelog

Breaking Change: Pipeline and pipeline stage delete endpoints will validate references by default starting with the 2026-09 API version


7/23/2026 Edit - The post has been updated to include the Deal object specific validateDealStageUsagesBeforeDelete query parameter.

Availability: This is a breaking change for the next GA date-based API version, /2026-09/. It does not change the behavior of the current GA API version or earlier versions. Integrations will see this behavior only after moving to /2026-09/ or later.

Learn more about HubSpot's Date Based Versioning

 

What is changing?

Starting in version /2026-09/ of the Pipelines API, HubSpot will validate references before deleting a pipeline or pipeline stage. If the pipeline or stage is in use, the delete request will be blocked and return a validation error.

This makes public API deletes behave the same way as deletes from the pipeline settings page in HubSpot, where deleting a pipeline or stage is already blocked when it is in use.

The reference check is enabled by default because validateReferencesBeforeDelete and validateDealStageUsagesBeforeDelete will default to true in /2026-09/.

validateDealStageUsagesBeforeDelete is used for the Deal object and validateReferencesBeforeDelete for all other object types.

To bypass this validation, pass:

validateReferencesBeforeDelete=false
validateDealStageUsageBeforeDelete=false
 

Affected endpoints

  • DELETE/crm/pipelines/{version}/{objectType}/{pipelineId}
  • DELETE/crm/pipelines/{version}/{objectType}/{pipelineId}/stages/{stageId}
  • PATCH/crm/pipelines/[version]/({objectType})/({pipelineId})
  • PUT/crm/pipelines/[version]/({objectType})/({pipelineId})

This change applies when {version} is /2026-09/ or a later DBV version.

 

Why does this matter?

This change makes pipeline deletion behavior consistent between the HubSpot UI and the public API, and helps prevent accidental deletion of pipelines or stages that are still referenced by existing objects.

Integrations that currently rely on deleting in-use pipelines or stages may receive a 400 validation error after upgrading to /2026-09/. To preserve the previous behavior, explicitly set validateReferencesBeforeDelete=false, or validateDealStageUsagesBeforeDelete, or remain on an earlier version until you are ready to migrate.

 

Migration guidance

Before upgrading to /2026-09/, review any integration logic that deletes pipelines or pipeline stages. If your integration expects deletes to succeed even when a pipeline or stage is in use, update the request to pass false to the above mentioned query parameters. Otherwise, handle the new validation error and prompt users to remove references before retrying the delete.

 

Question or comments? Join us in the community