Pipeline delete endpoints will validate references by default in 2026-09

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 will default to true in /2026-09/.

To bypass this validation, pass:

validateReferencesBeforeDelete=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 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 validateReferencesBeforeDelete=false. Otherwise, handle the new validation error and prompt users to remove references before retrying the delete.

 

Question or comments? Join us in the community