PlentyONE API Limits umgehen: Strategien für die reibungslose Datenextraktion

PlentyONE deckelt den API-Zugriff vierfach: lesende und schreibende Aufrufe, jeweils getrennt nach Minuten- und Tageskontingent. Migration und Tagesgeschäft ziehen dabei aus demselben Budget. Im Einstiegstarif sind das 80 lesende Aufrufe pro Minute und knapp 60.000 pro Tag – bei durchgehendem Höchsttempo nach rund zwölfeinhalb Stunden erschöpft, und zwar bevor eine einzige Bestellung verarbeitet wurde.

Wer ohne vorherige Messung extrahiert, bekommt eine von zwei Überraschungen: eine Projektlaufzeit, die sich vervielfacht, oder eine Marktplatz-Synchronisation, die mitten im Tagesgeschäft stehenbleibt.

Die Lösung liegt nicht in pauschalen Wartezeiten zwischen Requests, sondern in einer gemessenen, dynamisch gesteuerten Extraktionsstrategie. Wie diese aussieht, zeigt dieser Beitrag: von den harten Tarifzahlen über die Messmethodik bis zur Drosselungslogik im laufenden Extraktionsprozess.

Der Flaschenhals: Rate Limits und HTTP 429

PlentyONEs REST-API unterscheidet vier voneinander unabhängige Kontingente: lesende Calls pro Minute, lesende Calls pro Tag, schreibende Calls pro Minute und schreibende Calls pro Tag. Die dokumentierten Basiswerte unterscheiden sich stark je nach Tarif:

Diese Zahlen relativieren sich schnell: Im Basic-Tarif ist das Tageskontingent bei durchgehendem Höchsttempo (80 Calls/Minute) bereits nach rund 12,5 Stunden erschöpft – und das für ein System ganz ohne operativen Betrieb. Sobald Bestandsabgleiche, Bestellverarbeitung und Marktplatz-Synchronisation ihren Anteil beanspruchen, bleibt für eine Migration nur ein Bruchteil davon übrig.

Eine zweite, oft übersehene Grenze betrifft nicht das Volumen, sondern die Parallelität: PlentyONE begrenzt zusätzlich die Zahl gleichzeitig aktiver API-Sitzungen, standardmäßig auf drei. Wird dieses Limit überschritten, antwortet die API mit HTTP 429 und der Fehlerkennung too_many_concurrent_sessions. Für ein Migrationsprojekt heißt das konkret: Sind die vorhandenen Sitzungen bereits durch Marktplatz-Anbindungen oder Fulfillment-Dienstleister belegt, kann sich der Extraktionsprozess unter Umständen gar nicht erst anmelden. Diese Prüfung gehört zwingend in die Pre-Migration-Checkliste – nicht in die Fehlersuche am Go-Live-Wochenende.

In der Praxis bedeutet diese Sitzungsgrenze häufig, dass für die Migration eine der drei verfügbaren Sitzungen dediziert reserviert werden muss – notfalls durch temporäres Pausieren eines weniger kritischen Drittsystems während des Extraktionszeitraums. Diese Entscheidung sollte gemeinsam mit den Verantwortlichen für die betroffenen Drittanbindungen getroffen werden, nicht im Alleingang der Migrationsplanung.

Wird ein Kontingent überschritten, liefert die API eine eindeutig zuordenbare Fehlermeldung, etwa „short period read limit reached“ oder „long period write limit reached“. Diese Trennschärfe ist für die Steuerung wertvoll, weil sofort erkennbar ist, welches der vier Kontingente den Engpass verursacht.

Wichtige Einschränkung: Die Tabellenwerte sind die dokumentierten Basiswerte der Tarife. Die tatsächlich für ein konkretes System geltenden Limits können durch individuelle vertragliche Vereinbarungen abweichen und lassen sich zuverlässig nur aus dem Response-Header eines beliebigen API-Aufrufs ablesen.

Pre-Migration-Checkliste: API-Limits

Bevor ein Migrationsprojekt terminiert wird, sollten folgende Punkte geklärt sein:

• Welcher PlentyONE-Tarif ist aktuell aktiv, und welche Basiswerte gelten dafür laut Tarifdokumentation?
• Wie viele API-Sitzungen sind bereits durch Marktplatz-Anbindungen, Fulfillment-Dienstleister oder andere Drittsysteme belegt?
• Steht mindestens eine freie Sitzung für den Migrationsprozess zur Verfügung?
• Wurden die aktuellen Response-Header mindestens einmal ausgelesen, um die tatsächlich geltenden Limits zu bestätigen?
• Ist bekannt, wie viele der zu migrierenden Datenklassen bereits im bestehenden Shopsystem vorliegen und damit PlentyONE nicht zusätzlich belasten müssen?

Wird auch nur einer dieser Punkte übersprungen, drohen böse Überraschungen – meist nicht während der Planung, sondern mitten im laufenden Extraktionsprozess, wenn ein Tagesbetrieb plötzlich ins Stocken gerät.

API-Budget vor der Migration messen

Statt mit Schätzwerten zu planen, empfiehlt sich eine dedizierte Messphase von ein bis zwei Wochen vor Projektbeginn: Die Throttling-Header werden dabei im 15-Minuten-Takt ausgelesen und persistiert – rund 1.400 Messpunkte pro Woche, erzeugt durch weniger als 700 zusätzliche Aufrufe. Das beeinflusst das gemessene System praktisch nicht, liefert aber ein vollständiges Lastprofil über Tagesstunden und Wochentage hinweg.

Ein Auszug aus einem realen Response-Header zeigt das Prinzip:

x-plenty-global-long-period-limit: 564400
x-plenty-global-long-period-decay: 31038
x-plenty-global-long-period-calls-left: 558783
x-plenty-global-short-period-limit: 560
x-plenty-global-short-period-decay: 60
x-plenty-global-short-period-calls-left: 559

Aus diesen Werten lässt sich der verfügbare Spielraum unmittelbar ableiten: 564.400 Aufrufe Tageskontingent, davon zum Messzeitpunkt 558.783 offen, Rücksetzung in rund 8,6 Stunden. Zur Einordnung: Dieser konkrete Vertrag liegt im oberen Tarifsegment – gegenüber dem Basic-Tarif mit 59.760 lesenden Calls pro Tag entspricht das etwa dem Faktor 9,5. Die Spreizung zwischen zwei PlentyONE-Verträgen kann damit größer sein als der Unterschied zwischen zwei völlig verschiedenen Migrationsprojekten.

Aus dem gemessenen Lastprofil wird ein konservativer Anteil – als Ausgangswert häufig rund 60 Prozent des unbeanspruchten Kontingents – als Migrationsbudget definiert. Die verbleibenden 40 Prozent bleiben als Puffer für Lastspitzen und unvorhergesehene operative Vorgänge unangetastet. Entscheidend: Dieses Budget ist keine statische Tagessumme, sondern folgt dem gemessenen Verbrauchsprofil über den Tag – sonst würde die Migration das Kontingent in lastarmen Morgenstunden aufbrauchen und dem Abendgeschäft nichts hinterlassen.

Adaptive Throttling- und Retry-Strategien

Auf Basis dieses Profils prüft der Extraktionsprozess bei jedem Aufruf die aktuellen Header und drosselt in zwei Fällen: Fällt das Minutenkontingent unter rund 20 Prozent seiner Grenze, wird die Aufruffrequenz reduziert; fällt das Tageskontingent unter den für die aktuelle Stunde hinterlegten Schwellenwert, pausiert die Extraktion bis zum nächsten Zeitfenster. Ein Rate-Limit-Fehler ist in diesem Modell damit kein normaler Betriebszustand, sondern ein Signal, dass das Profil neu erhoben werden muss.

Wird ein Limit dennoch überschritten, liefert die API zusätzlich Retry-After (Wartezeit in Sekunden) sowie einen Zeitstempel im Feld Calls-Reset. Beide Werte gehören direkt in die Backoff-Logik – pauschale, feste Wartezeiten sind hier keine seriöse Lösung, weil sie weder die tatsächliche Kontingentlage noch tarifspezifische Unterschiede berücksichtigen.

Ein zusätzlicher, praktischer Aspekt der Authentifizierung sollte bei länger laufenden Extraktionen mitgeplant werden: Die Authentifizierung gegenüber der PlentyONE-REST-API erfolgt über OAuth 2.0, wobei der Login einen Bearer Token mit einer Gültigkeit von 24 Stunden liefert. Für einzelne, kurze Extraktionsläufe ist die Token-Erneuerung unkritisch. Für die im Folgenden beschriebene, über Tage laufende budgetgesteuerte Extraktion muss die Token-Erneuerung dagegen zwingend eingeplant werden, da der Prozess sonst mitten im Lauf durch einen abgelaufenen Token unterbrochen wird.

Bei besonders hohem PlentyONE-Anteil – etwa bei ausgeprägtem Marktplatzgeschäft – reicht selbst eine optimierte Steuerung manchmal nicht aus, um im gewünschten Zeitrahmen zu extrahieren. In diesem Fall wird nicht der Fertigstellungstermin, sondern das verfügbare API-Budget zur steuernden Größe: Die Extraktion läuft dann bewusst über Tage oder Wochen statt über Stunden, mit stärkerer Nutzung lastarmer Nachtzeiten. Eine Verdopplung der Entwicklerkapazität verkürzt diese Phase in diesem Fall nicht – die Terminplanung muss das entsprechend berücksichtigen.

Bulk- und effiziente Lesezugriffe

Neben der reinen Drosselung reduzieren zwei Techniken das benötigte Kontingent strukturell:

• with-Parameter: Verknüpfte Daten werden im selben Aufruf mitgeladen, statt sie über separate Folge-Requests nachzuziehen – ein einzelner Aufruf ersetzt so eine ganze Serie von Detailabfragen. Bei stark verschachtelten Datenstrukturen, etwa Bestellungen mit mehreren Positionen und zugehörigen Adressdaten, kann dieser einzelne Parameter die Zahl der benötigten Aufrufe um ein Vielfaches reduzieren.
• Delta-Filter über Zeitstempel: Filter der Form updated=gt:<Zeitstempel> begrenzen das Ergebnis auf tatsächlich veränderte Datensätze. Für wiederholte Testläufe und den finalen Delta-Abgleich vor dem Cutover ist das der wirksamste Einzelhebel, weil ein Wiederholungslauf dadurch nur noch einen Bruchteil des ursprünglichen Volumens erzeugt.

Ergänzend gilt: Einmal gelesene Daten sollten lokal zwischengespeichert und nicht bei jedem weiteren Testlauf erneut angefragt werden. In Kombination mit den Delta-Filtern entsteht daraus ein inkrementelles Extraktionsmodell statt wiederholter Vollabzüge – ein Unterschied, der sich bei mehreren Testmigrationen im Projektverlauf spürbar auf das verbrauchte Kontingent auswirkt.

Wichtig zur Einordnung: Nicht jede Datenklasse lässt sich über performante Bulk-Routen abrufen – einzelne Routen tragen eigene, engere Limits, die in der PlentyONE-REST-Dokumentation entsprechend gekennzeichnet sind. Eine pauschale „alles über Bulk“-Strategie funktioniert deshalb nicht.

Shopware als Entlastung

Der wirksamste Hebel liegt oft nicht in einer noch klügeren PlentyONE-Extraktion, sondern in der Frage, ob bestimmte Daten überhaupt erneut aus PlentyONE gezogen werden müssen. Artikel, Kategorien, Kunden und Bestellhistorie liegen bei bestehendem Shop-Betrieb häufig bereits vollständig im Shopsystem vor – dann lassen sie sich von dort beziehen, ohne das PlentyONE-Kontingent zusätzlich zu belasten.

Nicht jede Datenklasse lässt sich auf diesem Weg entlasten: Lagerbestände und Wareneingänge, Einkaufspreise und Lieferantendaten sowie Buchhaltungsbelege bleiben reine PlentyONE-Domänen ohne Shop-Bezug und müssen weiterhin direkt extrahiert werden. Für genau diese drei Domänen greifen dieselben bordeigenen Sparmechanismen der PlentyONE-REST-API – with-Parameter, Delta-Filter und persistente Zwischenspeicherung –, weil sich das Kontingentproblem hier nicht durch eine alternative Quelle umgehen lässt, sondern nur durch eine effizientere Nutzung der verbleibenden Aufrufe.

Wichtig: Das ist eine temporäre, migrationsspezifische Technik zur Schonung des API-Kontingents während der Übergangsphase – kein dauerhaftes Betriebsmodell. PlentyONE bleibt bis zum finalen Cutover durchgehend Master-System. Die konkrete Umsetzung dieser Strategie beschreiben wir in Shopware als Datenquelle nutzen.

Die Extraktion ist der erste von mehreren Migrationsschritten. Wo sie im Gesamtablauf steht und was danach folgt, zeigt unser Überblick zur Migration von PlentyONE zu Odoo.

Häufig gestellte Fragen zu PlentyONE API-Limits

Quellen

Die Rate-Limit-Mechanismen, Response-Header und das Drosselungsverhalten der PlentyONE REST API basieren auf der offiziellen Entwicklerdokumentation: PlentyONE REST API – Getting Started.

API-schonende Migration planen lassen

Wie viel Ihres tatsächlichen Migrationsbedarfs sich über das bestehende Shopsystem abdecken lässt und wie groß Ihr reales PlentyONE-Restkontingent ist, zeigt eine kurze technische Analyse Ihres Systems. Genau das ist Teil unseres kostenlosen, unverbindlichen E-Commerce Audits.

Lassen Sie Ihr API-Budget und Ihre Migrationsstrategie technisch bewerten – kostenfrei und unverbindlich.

Jetzt technische Migrationsanalyse anfordern

„Wir haben Sorge, dass eine Migration unseren laufenden Betrieb stört.“ Deshalb wird vorher gemessen, nicht geschätzt. Die Messphase selbst erzeugt weniger als 700 zusätzliche Aufrufe pro Woche und lässt Ihr Tagesgeschäft praktisch unberührt.

„Wir wissen nicht, welcher Tarif bei uns aktuell hinterlegt ist und was er tatsächlich erlaubt.“ Das klären wir gemeinsam als ersten Schritt der Analyse – zusammen mit einer Live-Auswertung Ihrer aktuellen Response-Header, die verlässlicher ist als jede Tarifdokumentation allein.

„Unsere IT hat keine Kapazität, eine solche Messphase selbst umzusetzen.“ Die Messung erzeugt nur wenige zusätzliche Aufrufe pro Stunde und läuft automatisiert im Hintergrund – der Aufwand für Ihr Team bleibt minimal.

✔ kostenlos   ✔ unverbindlich   ✔ auf Basis Ihrer echten API-Kontingente   ✔ Antwort innerhalb von 24 Stunden

Lukas Ehrenberg

Senior Shopware Developer & Integration Architect

Experte für Shopware 6, Odoo-Integrationen & ERP-Migrationen

Lukas Ehrenberg ist die operative Speerspitze der HQ GmbH, wenn es um komplexe und großvolumige E-Commerce-Infrastrukturen geht. In zahlreichen Projekten verantwortet er die technische Umsetzung von tiefgreifenden ERP-Migrationen – insbesondere den Wechsel von Legacy-Systemen wie PlentyONE hin zu modularen Plattformen wie Odoo. Gepaart mit seiner tiefen Shopware-Expertise baut er skalierbare Enterprise-Infrastrukturen auf. Seine enorme praktische Erfahrung macht ihn zum primären Ansprechpartner für Marken, die ein risikofreies, datensicheres und ausfallfreies Replatforming anstreben.

Als technischer Betreuer eines hochverfügbaren Enterprise-Shopware-Clusters mit über 14 Servern beherrscht er Lastverteilung und Systemstabilität im Hochfrequenzbereich. Seine besondere technische Expertise liegt in der architektonischen Neuausrichtung von E-Commerce-Ökosystemen: Er kombiniert fundiertes Wissen über die sichere Datenextraktion aus restriktiven Systemen (wie der PlentyONE REST-API unter strikter Optimierung von Rate-Limits) mit der performanten, asynchronen Anbindung an moderne ERP-Lösungen wie Odoo. Damit garantiert er nahtlose Systemübergänge selbst bei höchsten Transaktionsvolumina.

Vollständiges Profil & Fachartikel ansehen