HubSpot Pipelines API: Löschvalidierung ab 2026-09 Pflicht

Was sich an der Pipelines API ändert

Ab der API-Version 2026-09 der HubSpot Pipelines API blockiert HubSpot das Löschen einer Pipeline oder Pipeline-Stage, wenn diese noch in Verwendung ist. Der Request liefert in diesem Fall einen Validierungsfehler, statt die Pipeline oder Stage tatsächlich zu entfernen. Damit verhält sich die öffentliche API künftig genauso wie die Pipeline-Einstellungen in der HubSpot-Oberfläche, wo eine Löschung bereits seit längerem verhindert wird, solange die Pipeline oder Stage noch referenziert wird.

Technisch steckt die Änderung in zwei Query-Parametern: validateReferencesBeforeDelete für alle Objekttypen außer Deals und validateDealStageUsagesBeforeDelete speziell für das Deal-Objekt. Beide Parameter springen in Version 2026-09 standardmäßig auf true. Wer die alte, ungeprüfte Löschung weiterhin braucht, muss den jeweiligen Parameter explizit auf false setzen. Details dazu stehen im offiziellen HubSpot Changelog.

Welche Endpunkte sind betroffen?

Laut Changelog betrifft die Änderung mindestens folgende Endpunkte:

• DELETE /crm/pipelines/{version}/{objectType}/{pipelineId}: Löschen einer kompletten Pipeline
• DELETE /crm/pipelines/{version}/{objectType}/{pipelineId}/stages/{stageId}: Löschen einer einzelnen Stage
• ein zugehöriger PATCH-Endpunkt im selben Pfad, über den Stage-Änderungen laufen

Wichtig: Die Änderung gilt ausschließlich für Integrationen, die explizit auf /2026-09/ oder eine spätere Version wechseln. Wer aktuell eine ältere, bereits als GA markierte Version anspricht, bemerkt zunächst nichts. HubSpots date-based Versionierung sieht vor, dass Breaking Changes nur in neu veröffentlichten Versionsständen landen, nicht rückwirkend in bestehenden.

Warum diese Änderung für RevOps-Teams relevant ist

In der Praxis werden Pipelines und Stages selten isoliert gelöscht. Sie hängen an Deals, Tickets, Workflows, Reports und oft an individuellen Automatisierungen, die auf eine bestimmte Stage-ID reagieren. Wird eine Stage per API entfernt, obwohl noch Datensätze darauf verweisen, entstehen verwaiste Referenzen: Deals landen in einer nicht mehr existierenden Stage, Reports zeigen Lücken, Workflows laufen ins Leere, ohne dass das sofort auffällt.

Solche Situationen treten typischerweise bei größeren Aufräumaktionen auf, etwa wenn nach einer Fusion zwei CRM-Instanzen zusammengeführt werden und doppelte oder veraltete Pipelines bereinigt werden sollen. Wer dafür Migrationsskripte oder Bulk-Löschjobs einsetzt, sollte die neue Validierung als Schutzmechanismus verstehen, nicht als Hindernis. Sie verhindert genau die Art von Dateninkonsistenz, die sich im Nachhinein nur mit manuellem Aufwand korrigieren lässt. Eine strukturierte Vorgehensweise für solche Zusammenführungen beschreiben wir in der Checkliste zur CRM-Konsolidierung nach M&A.

Wie Integrationen sich jetzt vorbereiten sollten

Für Teams, die eigene Skripte, Middleware oder ETL-Jobs gegen die Pipelines API betreiben, ergeben sich aus der Änderung konkrete Aufgaben:

• Bestehenden Code durchgehen, der Pipelines oder Stages per DELETE-Request entfernt, und prüfen, ob dort bislang keine Prüfung auf Verwendung stattfindet.
• Festlegen, wie mit dem neuen Validierungsfehler umgegangen wird: Abfangen und Datensätze vorher in eine andere Stage verschieben, oder bewusst mit validateReferencesBeforeDelete=false beziehungsweise validateDealStageUsageBeforeDelete=false umgehen und die Konsequenzen selbst tragen.
• Den Wechsel auf /2026-09/ in einer Sandbox oder einem Test-Account durchspielen, bevor produktive Integrationen umgestellt werden.

Diese Änderung reiht sich in eine Serie von Anpassungen ein, mit denen HubSpot seine CRM-API im Jahr 2026 strenger auf Datenintegrität ausrichtet. Parallel dazu werden ab derselben Versionsgrenze auch zusätzliche Validierungsregeln beim Schreiben von CRM-Daten Pflicht. Wer seine Integrationen ohnehin für diesen Versionswechsel vorbereitet, sollte beide Änderungen gemeinsam einplanen, statt sie nacheinander abzuarbeiten.

Einordnung: date-based Versionierung als Rahmen

HubSpot veröffentlicht Breaking Changes an der CRM-API grundsätzlich nur in neuen, datumsbasierten Versionsständen wie /2026-09/. Bestehende Integrationen auf älteren Versionen laufen unverändert weiter, bis HubSpot diese Versionen irgendwann offiziell abkündigt. Das gibt Unternehmen Zeit, verschafft aber keinen Freifahrtschein auf Dauer: Wer die Versionshistorie nicht aktiv verfolgt, läuft Gefahr, bei einer späteren Zwangsmigration mehrere Breaking Changes gleichzeitig abarbeiten zu müssen statt einzeln. Diese Verschärfung reiht sich ein in eine ganze Serie technischer Anpassungen, die HubSpot im Jahr 2026 vorgenommen hat, von neuen Owner-Limits bis zu Webhook-Änderungen, die wir im Überblick zu den HubSpot-Updates im Juli 2026 zusammengefasst haben. Ein regelmäßiger Blick in den Changelog gehört damit zur Grundpflege jeder produktiven HubSpot-Integration.

Häufig gestellte Fragen

Ab wann gilt die neue Validierung beim Löschen von Pipelines?

Die Validierung greift ausschließlich ab API-Version /2026-09/ der Pipelines API. Integrationen, die auf der aktuellen GA-Version oder älteren Versionen laufen, sind davon nicht betroffen.

Wie lässt sich die Validierung bei Bedarf umgehen?

Für die meisten Objekttypen lässt sich der Parameter validateReferencesBeforeDelete=false setzen, für das Deal-Objekt gilt stattdessen validateDealStageUsageBeforeDelete=false. In beiden Fällen wird die Pipeline oder Stage dann auch gelöscht, wenn noch Referenzen bestehen.

Betrifft die Änderung auch das Löschen über die HubSpot-Oberfläche?

Nein. Auf der Pipeline-Einstellungsseite der HubSpot-Oberfläche war eine Löschung bei aktiver Verwendung schon vorher blockiert. Die API-Änderung gleicht lediglich das Verhalten der öffentlichen API an diesen bereits bestehenden UI-Schutz an.

Was passiert mit laufenden Migrationsskripten, die derzeit auf einer älteren Version arbeiten?

Solange diese Skripte nicht explizit auf /2026-09/ oder eine spätere Version umgestellt werden, ändert sich ihr Verhalten nicht. Der Breaking Change wirkt erst mit dem aktiven Versionswechsel.