Legt Ihre Warenwirtschaft, Ihr ERP oder Ihr Retourentool Erstattungen per Schnittstelle mit eigenen Beträgen je Bestellposition an, kann WooCommerce 11.3 solche Erstattungen ablehnen. Testen Sie diese Anbindungen deshalb vor dem Update auf einer Kopie Ihres Shops und sorgen Sie dafür, dass eine abgelehnte Erstattung sofort auffällt. Läuft 11.3 bereits, gleichen Sie zuerst die Erstattungen seit dem Update ab. Sonst wartet ein Kunde auf sein Geld, obwohl im System alles erledigt aussieht.
Was ändert sich bei Erstattungen in WooCommerce 11.3?
Stand: 18.11.2026: WooCommerce 11.3.0 ist seit dem 11.11.2026 verfügbar und laut den Release Notes zu WooCommerce 11.3.0 abwärtskompatibel, enthält aber ein Datenbank-Update. Eine Rückerstattung per REST API ist eine Erstattung, die ein externes System über die Schnittstelle (API) von WooCommerce anlegt, statt dass jemand sie im Shop-Backend erfasst.
Genau diese Erstattungen prüft WooCommerce jetzt strenger. Laut den Entwicklerhinweisen von WooCommerce zu Version 11.3 kontrolliert der Endpunkt POST /wp-json/wc/v3/orders/{order_id}/refunds ausdrücklich übergebene Beträge je Position, bevor er eine Erstattung anlegt. Folgende Regeln gelten:
- Jede Position mit Betrag muss zu einem Produkt, einer Gebühr oder einer Versandposition derselben Bestellung gehören.
- Der Betrag je Position samt Steuer darf den noch erstattbaren Rest dieser Position nicht übersteigen.
- Die Summe aller Positionen samt Steuer darf den Gesamtbetrag der Erstattung nicht übersteigen.
- Das Vorzeichen muss zur Position passen. Negative Erstattungen bleiben für negative Positionen wie Rabattgebühren gültig.
Ungültige Anfragen beantwortet WooCommerce mit HTTP 400 oder 422 und einem Fehlercode, der mit woocommerce_rest_ beginnt. Eine Erstattung entsteht dann nicht. Im zugehörigen Pull Request im WooCommerce-Repository stehen drei konkrete Codes:
| Fehlercode | HTTP-Status | Typischer Auslöser |
|---|---|---|
| woocommerce_rest_invalid_refund_amount | 400 | Positionsbeträge übersteigen den angegebenen Gesamtbetrag. Herstellerbeispiel: amount "3" mit refund_total 4 für eine Position. |
| woocommerce_rest_refund_total_exceeds_line | 422 | Der Betrag für eine Position liegt über ihrem ursprünglichen Wert. |
| woocommerce_rest_refund_total_exceeds_remaining | 422 | Die Position wurde schon teilweise erstattet, der neue Betrag übersteigt den Rest. |
Anfragen, die nur Mengen übergeben, verhalten sich laut Pull Request wie bisher. Neu in 11.3 ist außerdem eine Einstellung für die Seite mit Ihrer Erstattungs- und Rückgaberichtlinie.
Ist Ihr Shop betroffen?
Der erste Prüfschritt ist einfach: Sehen Sie in der Pluginliste Ihres Shops nach, welche WooCommerce-Version installiert ist. Die Update-Anleitung von WooCommerce führt dafür über "Plugins > Installed Plugins". Steht dort eine Version vor 11.3, testen Sie Ihre Anbindungen wie unten beschrieben vor dem Update. Läuft bereits 11.3, gleichen Sie die seit dem Update in der Warenwirtschaft angelegten Erstattungen mit den Bestellungen in WooCommerce ab und prüfen das Fehlerprotokoll Ihres Connectors auf HTTP 400 oder 422. Laut WooCommerce sind solche Antworten Validierungsfehler, bei denen keine Erstattung angelegt wurde.
Danach klären Sie mit Ihrer Shop-Betreuung oder dem Anbieter Ihrer Warenwirtschaft, ob Erstattungen per API in WooCommerce angelegt werden und ob dabei Beträge je Position mitgeschickt werden. Oft steht das auch in der Dokumentation des Connectors. Wer Erstattungen ausschließlich im WooCommerce-Backend über die Schaltfläche "Refund" anlegt, ist von dieser API-Änderung nicht direkt betroffen.
Die folgende Matrix ist eine redaktionelle Entscheidungshilfe auf Basis der Herstellerangaben. Sie ersetzt keinen Test mit Ihrer eigenen Anbindung.
| Erstattungsweg | Betroffen? | Nächster Schritt |
|---|---|---|
| Nur im WooCommerce-Backend | Nicht direkt | Ablauf wie gewohnt, nach dem Update kurz kontrollieren |
| Warenwirtschaft oder ERP mit Beträgen je Position | Ja | Auf Staging testen, Fehlerbehandlung prüfen |
| Warenwirtschaft oder ERP nur mit Mengen | Laut Hersteller unverändert | Mit einem Testfall bestätigen |
| Retourentool legt Erstattungen per API an | Abhängig von der Übergabe | Beim Anbieter klären, ob Beträge je Position gesendet werden |
| Erstattung direkt im Dashboard des Zahlungsanbieters | Nicht über diesen Endpunkt | Prüfen, wie die Erstattung danach in WooCommerce landet |
Wenn Sie mehrere Systeme an WooCommerce angebunden haben, lohnt ein Blick auf die gesamte Anbindung von Warenwirtschaftssystemen. Erstattungen sind dort ein Datenfluss unter vielen.
Wie testen Sie Erstattungen vor dem Update?
Ein Test auf einer Kopie des Shops zeigt Ihnen vor dem Live-Update, ob Ihre Anbindung mit den neuen Regeln zurechtkommt.
Schritt 1: Erstattungswege erfassen
Listen Sie alle Systeme auf, die Erstattungen in WooCommerce anlegen: ERP, Warenwirtschaft, Retourentool, eigene Skripte. Notieren Sie je System, ob es Mengen oder Beträge je Position überträgt und wer es technisch betreut.
Schritt 2: Staging mit 11.3 aufsetzen
Die Update-Anleitung von WooCommerce empfiehlt ein Backup und eine Staging-Umgebung, also eine Kopie des Shops zum Testen. Dort heißt es: "Do not test updates directly on your production site." Spielen Sie 11.3 auf der Kopie ein und führen Sie das Datenbank-Update über "Update WooCommerce Database" aus, wenn der Hinweis erscheint. Verbinden Sie die Testsysteme mit der Kopie, nie mit dem Live-Shop.
Schritt 3: Testfälle durchspielen
Die Tabelle ist eine Vorlage für Ihren Testplan. Die Fehlercodes stammen aus den Herstellerangaben, die Fälle müssen Sie mit Ihren eigenen Testbestellungen füllen.
| Testfall | Erwartetes Ergebnis | Worauf achten |
|---|---|---|
| Vollerstattung einer Bestellung | Erstattung wird angelegt | Summe der Positionen gleich Gesamtbetrag |
| Teilerstattung einer Position | Erstattung wird angelegt | Steuer je Position korrekt mitgerechnet |
| Zweite Teilerstattung derselben Position | Angelegt, solange Rest reicht | Über dem Rest folgt woocommerce_rest_refund_total_exceeds_remaining |
| Bestellung mit Rabatt oder Gebühr | Angelegt bei passendem Vorzeichen | Negative Positionen mit negativem Betrag |
| Nur Versandkosten erstatten | Erstattung wird angelegt | Versandposition derselben Bestellung |
| Positionsbeträge größer als Gesamtbetrag | Ablehnung mit 400 | woocommerce_rest_invalid_refund_amount kommt im eigenen System an |
Achten Sie besonders auf Rundungsdifferenzen. WooCommerce vergleicht die Beträge laut Pull Request in der Genauigkeit der Bestellwährung.
Schritt 4: Fehlerbehandlung und Live-Update
WooCommerce rät: "Check the response before treating a refund as created, and correct the allocation rather than retrying the same payload." Ihr System sollte also erst nach einer erfolgreichen Antwort "erstattet" vermerken und bei 400 oder 422 eine Meldung an eine zuständige Person schicken. Dieselbe Anfrage erneut zu senden, bringt nichts. Nach dem Live-Update kontrollieren Sie die ersten Erstattungen im Backend und in den Bestellnotizen. Bei automatischen Erstattungen über das Zahlungsgateway erscheint dort laut WooCommerce in der Regel "Successfully refunded". Wenn Sie Upgrades regelmäßig planen möchten, hilft eine WooCommerce-Betreuung mit Upgradeplanung.
Warum ist eine abgelehnte Erstattung rechtlich heikel?
Nach einem Widerruf müssen Händler das Geld innerhalb von 14 Tagen zurückzahlen. § 357 BGB schreibt vor, dass empfangene Leistungen spätestens nach 14 Tagen zurückzugewähren sind, und zwar mit demselben Zahlungsmittel, außer es wurde ausdrücklich etwas anderes vereinbart und dem Kunden entstehen keine Kosten. Laut der Verbraucherzentrale zum Widerruf beginnt diese Frist mit Erhalt der Widerrufserklärung.
Wird eine Erstattung aus der Warenwirtschaft abgelehnt und niemand bemerkt es, kann intern "erstattet" stehen, während der Kunde kein Geld erhält. So kann die Frist unbemerkt verstreichen. Eine saubere Fehlerbehandlung schützt also Ihre Kundenbeziehung und Ihre Fristen.
Hinweis: Dieser Abschnitt ist keine Rechtsberatung. Händler dürfen die Rückzahlung bei Waren laut Verbraucherzentrale zurückhalten, bis die Ware zurück ist oder ein Einlieferungsbeleg vorliegt. Mehr zum Widerruf im Checkout lesen Sie in unserem Beitrag zum Digital Fairness Act.
Welche Alternativen gibt es, wenn die Schnittstelle noch nicht passt?
Kommt Ihre Anbindung mit 11.3 noch nicht zurecht, haben Sie mehrere Wege. Die Tabelle stellt sie kurz gegenüber.
| Weg | Wann sinnvoll | Abwägung |
|---|---|---|
| Erstattung manuell im Backend | Wenige Erstattungen, schnelle Lösung | Bei "Refund $[refund amount] manually" zahlen Sie das Geld selbst über den Zahlungsanbieter oder per Überweisung zurück |
| Nur Mengen übergeben | Connector bietet diese Einstellung | Verhalten laut Hersteller unverändert, Beträge berechnet WooCommerce |
| Update verschieben | Anpassung ist beauftragt, aber nicht fertig | Nur kurz aufschieben: WooCommerce empfiehlt einen regelmäßigen Update-Rhythmus und frühere Updates bei Sicherheitskorrekturen |
| Schnittstelle anpassen lassen | Erstattungen laufen regelmäßig per API | Dauerhafte Lösung, Aufwand hängt vom Connector ab |
Die Schnittstelle anzupassen ist für Shops mit vielen Retouren der stabilste Weg.
Häufige Fragen
Betrifft die Änderung auch Erstattungen im WooCommerce-Backend?
Die neue Prüfung gilt für den REST-API-Endpunkt für Erstattungen. Wer im Backend über "Refund" und danach "Refund $[refund amount] via [payment gateway]" oder "Refund $[refund amount] manually" erstattet, nutzt diesen Weg nicht direkt.
Woran erkenne ich eine abgelehnte Erstattung?
Die API antwortet mit HTTP 400 oder 422 und einem Fehlercode wie woocommerce_rest_invalid_refund_amount oder woocommerce_rest_refund_total_exceeds_remaining. In WooCommerce fehlt die Erstattung dann in der Bestellung. Ihr angebundenes System sollte diese Antwort protokollieren und melden.
Werden Erstattungen nur mit Mengenangaben weiter angenommen?
Ja. Laut dem Pull Request bei WooCommerce behalten Anfragen, die nur Mengen übergeben, ihr bisheriges Verhalten. Bestätigen Sie das trotzdem mit einem Testfall auf Staging.
Wie aufwendig ist der Test?
Der Aufwand hängt davon ab, wie viele Systeme Erstattungen anlegen, ob eine Staging-Umgebung bereits existiert und ob Ihr Connector sich mit einer Testkopie des Shops verbinden lässt. Mit einer vorhandenen Kopie, ein paar Testbestellungen und einem Testplan wie oben ist der Test gut planbar.
Muss ich wegen 11.3 meine MCP- oder KI-Anbindung ändern?
Nur wenn Ihr KI-Client noch den bisherigen WooCommerce-MCP-Zugang nutzt. Diese Umstellung ist ein eigener Schritt, den wir in unserem Beitrag WooCommerce MCP vor Version 11.3 umstellen erklären. Für Erstattungen über die reguläre REST API gilt dieser Artikel.
Was passiert, wenn das Zahlungsgateway keine automatische Erstattung unterstützt?
Dann erfasst WooCommerce die Erstattung nur im Shop. Laut der WooCommerce-Anleitung zu Rückerstattungen zahlen Sie das Geld in diesem Fall selbst über das Dashboard des Zahlungsanbieters oder per Überweisung zurück.
Quellen
- WooCommerce Developer Blog: WooCommerce 11.3.0 release notes, developer.woocommerce.com
- WooCommerce Developer Blog: WooCommerce 11.3: What's coming for developers, developer.woocommerce.com
- GitHub woocommerce/woocommerce: Fix invalid line item amounts in REST refunds (PR #69302), github.com
- WooCommerce Docs: WooCommerce Refunds, woocommerce.com
- WooCommerce Docs: How to update WooCommerce, woocommerce.com
- Bundesministerium der Justiz: § 357 BGB, gesetze-im-internet.de
- Verbraucherzentrale: Widerruf beim Onlineshopping, verbraucherzentrale.de
Alle Quellen abgerufen am 18. November 2026.
Erstattungen vor dem Update testen?
Im kostenlosen Erstgespräch klären wir, welche Ihrer Systeme Erstattungen in WooCommerce anlegen und wie Sie das Update auf 11.3 sicher testen.