Shopify-Bestellungen per API bearbeiten: Sicherer Ablauf von Beginn bis Abschluss

Warum die drei API-Phasen wichtig sind#

Die Bestellbearbeitung ist eine Transaktion, keine einzelne Aktualisierung. Shopify erstellt eine berechnete Version der Bestellung. Die App merkt daran Änderungen vor und übernimmt diese Version beim Abschluss.

Bei über 10 Mio. Bestellungen in Shops mit Revize wurde etwa jede 19. Bestellung, also 5,2 %, nach dem Checkout bearbeitet (Revize, 2026). Bei diesem Volumen sollte die Bestellbearbeitung ein regulärer Betriebsablauf sein und kein Ausnahmefall für den Support.

CalculatedOrder ist wie ein Korrekturabzug einer Kommissionierliste. Sie können Positionen hinzufügen oder entfernen, das Ergebnis prüfen und dann eine endgültige Version übernehmen.

Der Zeitpunkt ist genauso wichtig wie korrekte API-Aufrufe. In Shops mit Revize erfolgt die mittlere Bearbeitung 4,6 Minuten nach dem Checkout (Revize, 2026). Beginnt die Kommissionierung in diesem Zeitraum, kann technisch korrekter Code trotzdem zum falschen Paket führen.

So funktioniert die Shopify API zur Bestellbearbeitung#

Für die Shopify Admin API 2026-07 lautet der Ablauf: orderEditBegin, eine oder mehrere Mutationen zum Vormerken von Änderungen und danach orderEditCommit. Die Mutationsreferenzen von Shopify akzeptieren beim Vormerken und Abschließen entweder die ID der berechneten Bestellung oder die ID der Bearbeitungssitzung. Diese Anleitung verwendet durchgehend calculatedOrder.id.

1. Rufen Sie orderEditBegin mit der Shopify-Bestell-ID auf.
2. Speichern Sie calculatedOrder.id als $calculatedOrderId.
3. Führen Sie jede Mutation zum Vormerken mit dieser ID aus.
4. Prüfen Sie die berechneten Positionen, Summen und jedes userErrors-Array.
5. Übergeben Sie dieselbe ID an orderEditCommit.

Shopify dokumentiert dieses Modell aus Beginn, Vormerken und Abschluss. Die App benötigt den Zugriffsbereich write_order_edits.

Eine minimale Begin-Mutation kann beide Objekte für die Fehleranalyse abrufen und zugleich eine ID für den weiteren Ablauf auswählen:

mutation BeginOrderEdit($orderId: ID!) {
  orderEditBegin(id: $orderId) {
    calculatedOrder {
      id
      lineItems(first: 50) {
        nodes {
          id
          quantity
        }
      }
    }
    orderEditSession {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Brechen Sie ab, wenn userErrors nicht leer ist. Eine erfolgreiche Netzwerkanfrage belegt nur, dass Shopify die Anfrage empfangen hat. Sie belegt nicht, dass Shopify den Vorgang akzeptiert hat.

Die versionierte Anleitung zur Bestellbearbeitung dokumentiert Mutationen zum Vormerken von Varianten, Mengen, benutzerdefinierten Artikeln, Rabatten auf Bestellpositionen und Versandpositionen. Prüfen Sie vor der Implementierung und vor jedem Wechsel der API-Version die passende Mutationsreferenz für 2026-07.

So setzen Sie einen vollständigen Variantenwechsel um#

Bei einem Variantenwechsel fügen Sie den Ersatz hinzu und setzen die ursprüngliche berechnete Bestellposition innerhalb derselben Bearbeitungssitzung auf null. Schließen Sie die Bearbeitung erst ab, wenn beide Vorgänge erfolgreich waren und das berechnete Ergebnis der Bestätigung des Kunden entspricht.

Angenommen, ein Kunde hat Größe M bestellt und benötigt Größe L.

1. Beginnen Sie die Bearbeitung und speichern Sie calculatedOrder.id.
2. Fügen Sie die Variante in Größe L mit dieser ID hinzu:

mutation AddReplacement(
  $calculatedOrderId: ID!
  $variantId: ID!
  $quantity: Int!
) {
  orderEditAddVariant(
    id: $calculatedOrderId
    variantId: $variantId
    quantity: $quantity
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

3. Suchen Sie die ursprüngliche Variante in Größe M in der berechneten Bestellung. Verwenden Sie deren berechnete Bestellpositions-ID. Übernehmen Sie die ID einer Position aus der ursprünglichen Bestellung nicht, ohne den zurückgegebenen berechneten Zustand zu prüfen.

4. Setzen Sie die ursprüngliche Position auf null:

mutation RemoveOriginal(
  $calculatedOrderId: ID!
  $lineItemId: ID!
) {
  orderEditSetQuantity(
    id: $calculatedOrderId
    lineItemId: $lineItemId
    quantity: 0
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

5. Fragen Sie die berechnete Bestellung erneut ab. Prüfen Sie, ob der Ersatz vorhanden ist, die ursprüngliche Menge null beträgt und die Summen mit der Kundenbestätigung übereinstimmen.
6. Schließen Sie die Bearbeitung mit derselben ID der berechneten Bestellung ab:

mutation CommitOrderEdit(
  $calculatedOrderId: ID!
  $notifyCustomer: Boolean!
  $staffNote: String
) {
  orderEditCommit(
    id: $calculatedOrderId
    notifyCustomer: $notifyCustomer
    staffNote: $staffNote
  ) {
    order {
      id
      updatedAt
    }
    userErrors {
      field
      message
    }
  }
}

Warnung: Schließen Sie die Bearbeitung nicht ab, wenn das Hinzufügen erfolgreich war, das Entfernen aber noch nicht. Sonst wird aus dem Wechsel ein zusätzlicher Artikel.

Weisen Sie doppelte Klicks auf die Bestätigung zurück, halten Sie die abgeschlossene Phase fest und rufen Sie die Bestellung vor dem Abschluss erneut ab, wenn ein anderer Prozess sie geändert haben könnte.

Welche Mutation für welche Änderung zuständig ist#

Verwenden Sie den Ablauf mit berechneter Bestellung für Änderungen an Bestellpositionen, Mengen, Rabatten und Versandpositionen. Nutzen Sie orderUpdate sowie Mutationen für Stornierungen und Rückerstattungen nur für die Aufgaben, die ihre versionierten Referenzen dokumentieren.

Die Referenz zu orderUpdate für 2026-07 umfasst Attribute wie die E-Mail-Adresse des Kunden, Lieferadresse, Tags und Metafelder. Ihre Beispiele dokumentieren auch Änderungen an Notizen. Für größere Änderungen wie das Hinzufügen oder Entfernen von Bestellpositionen, Mengenänderungen oder Änderungen an Rabatten verweist sie auf orderEditBegin.

Laut Shopifys Hinweisen zur Bestellbearbeitung können Rabattcodes, automatische Rabatte und Skriptrabatte nicht bearbeitet werden. Rabatte auf die gesamte Bestellung können ebenfalls weder hinzugefügt noch entfernt oder geändert werden. Mutationen für Rabatte auf Bestellpositionen heben diese Grenzen nicht auf.

Wo die Shopify API zur Bestellbearbeitung endet#

Eine abgeschlossene Bearbeitung und die finanzielle Abwicklung sind getrennte Prüfpunkte. Shopify weist darauf hin, dass nach einer Änderung der Gesamtsumme ein offener Betrag vom Kunden zu zahlen oder eine Rückerstattung fällig sein kann.

Rufen Sie bei einer höheren Gesamtsumme die abgeschlossene Bestellung erneut ab. Prüfen Sie, wie der offene Betrag eingezogen wird, bevor Sie die Bestellung für das Fulfillment freigeben. Eine erfolgreiche Antwort von orderEditCommit belegt nicht, dass die Zahlung abgeschlossen ist.

Bei einer niedrigeren Gesamtsumme ersetzt der Abschluss keinen gezielten Rückerstattungsablauf. Berechnen Sie den vorgesehenen Betrag, rufen Sie den passenden Rückerstattungsvorgang auf und prüfen Sie dessen Antwort. Eine Änderung ohne Betragsdifferenz erfordert weder einen Zahlungseinzug noch eine Rückerstattung, aber weiterhin eine abschließende Prüfung des Bestellstatus.

Abonnieren Sie Shopifys Webhook orders/edited und rufen Sie die Bestellung erneut ab, bevor ein nachgelagertes System handelt. Webhooks sind ein Signal, den aktuellen Datensatz zu lesen. Sie sind keine Grundlage, einer früheren lokalen Kopie zu vertrauen.

Lassen Sie einen externen Logistikdienstleister (3PL) keine Bestellung kommissionieren, deren Bearbeitungs- oder Zahlungsstatus ungeklärt ist. Testen Sie die Sperre, die Regel zum Zahlungsstatus oder das Freigabesignal mit dem Lagersystem, das die Bestellungen tatsächlich herunterlädt.

So finden Sie die Ursache von Bearbeitungsfehlern#

Prüfen Sie zuerst die Bearbeitbarkeit, IDs, Validierung und gleichzeitige Änderungen. Protokollieren Sie den Mutationsnamen, die Shopify-Bestell-ID, die gewählte Bearbeitungs-ID und das vollständige userErrors-Array, ohne Kunden- oder Zahlungsgeheimnisse zu erfassen.

Laut Shopifys Anforderungen an die Bestellbearbeitung benötigen Apps write_order_edits. Sie können nur Bestellpositionen bearbeiten, für die noch kein Fulfillment erfolgt ist, und weder archivierte Bestellungen noch Bestellungen bearbeiten, die vor dem 1. Januar 2019 aufgegeben wurden. Standardmäßig haben Apps Zugriff auf Bestellungen der letzten 60 Tage. Für die Abfrage älterer Bestellungen ist read_all_orders erforderlich.

Das sind getrennte Regeln. read_all_orders erweitert den Zugriff auf ältere Datensätze. Archivierte Bestellungen oder Bestellungen von vor 2019 werden dadurch nicht bearbeitbar.

Richten Sie das Verhalten der App nicht nach einer vermuteten Fehlermeldung aus. Lesen Sie das zurückgegebene Feld und die Meldung für die konkrete Anfrage. Reproduzieren Sie den Fehler anschließend mit einer kontrollierten Testbestellung.

Mit Revize arbeiten oder auf APIs aufbauen#

Revize ist die naheliegende Wahl, wenn Kunden ihre Bestellungen vor dem Fulfillment selbst bearbeiten sollen. Eigener Code eignet sich für interne Abläufe mit besonderen Anforderungen. Entscheidend ist, ob Sie eine fertige Kundenerfahrung nutzen oder jede Oberfläche, jeden Zustandswechsel und jede Absicherung für das Lager selbst verantworten möchten.

Eigener Code ist sinnvoll, wenn ein Händler eine spezielle Oberfläche für Mitarbeiter oder einen Genehmigungsprozess über interne Systeme hinweg benötigt. Revize bietet weder eine allgemeine API zur Bestellbearbeitung noch eine Genehmigungswarteschlange für Händler.

Agenturen können dokumentierte Shopify Flow-Trigger mit Bearbeitungsereignissen von Revize verbinden, Bearbeitungs- und Freigabe-Tags von Revize in ihrer Fulfillment-Logik verwenden oder die Public Cancellation API für eine externe Stornierungsoberfläche nutzen. Die Public Cancellation API ist nur in Pro verfügbar, muss vom Support aktiviert werden und setzt das Bearbeitungsfenster, die Einschränkungen und die Rückerstattungsregeln des Portals durch.

Von den Änderungen nach dem Kauf in Shops mit Revize wurden 92,2 % von Kunden ohne Supportmitarbeiter abgeschlossen (Revize, 2026). Der Leitfaden für Agenturen zur Bestellbearbeitung nach dem Kauf behandelt die Vorarbeit vor der Implementierung.

Die verfügbaren Funktionen hängen vom Plan ab. Produkte hinzufügen und wechseln, Rückerstattungen als Shop-Guthaben, die Neuberechnung von Rabatten, Versand und Steuern, die Regel-Engine, Reverse Unpaid Edits und die Public Cancellation API sind nur in Pro verfügbar. Einzelheiten stehen in der Revize-Dokumentation zur Abrechnung.

Installieren Sie Revize: Order Editing & Upsell, wenn Sie eine funktionierende Selbstbedienung für Kunden benötigen.

So schließt Revize den Ablauf ab#

Revize bietet Kunden einen kontrollierten Bearbeitungsablauf auf Shopifys Bestellstatusseite. Der Händler legt das Zeitfenster, die verfügbaren Aktionen, die Rückerstattungsregeln und den Modus für die Bestellverarbeitung fest.

Erhöht eine Änderung die Gesamtsumme, zeigt Revize Jetzt bezahlen an und leitet den Kunden zum Shopify Checkout weiter, um ausschließlich die Differenz zu bezahlen. Bei einer niedrigeren Summe erscheint Rückerstattung, bei unveränderter Summe Bestätigen. Shopify führt die Zahlung oder Rückerstattung aus, wie im Kundenablauf von Revize beschrieben.

Der Händler legt den Zeitraum unter Order Editing > Order edit window fest. Die Anleitung zum Bearbeitungsfenster dokumentiert feste Vorgaben, eigene Zeitspannen, geplante Fristen und einen Modus bis zum Fulfillment. Dieser Modus sperrt eine Bestellung nicht automatisch.

Im empfohlenen Verarbeitungsmodus setzt Revize während des Bearbeitungsfensters eine Shopify Fulfillment-Sperre und hebt sie auf, sobald die Bearbeitung geschlossen wird. Für Systeme, die Sperren ignorieren, kann die dokumentierte Alternative über die manuelle Zahlungserfassung nötig sein. Stattdessen kann ein Freigabe-Tag einem Fulfillment-System, das auf dieses Tag wartet, die Freigabe signalisieren.

Revize prüft den aktuellen Bestand unter Berücksichtigung der Versandzone, bevor Kunden eine Variante wechseln können. Der Leitfaden zu Fulfillment-Sperren behandelt den Lagerteil des Ablaufs.

Was Sie diese Woche testen sollten#

Testen Sie eine Bestellung vom Checkout bis zum korrigierten Fulfillment, einschließlich möglicher Fehler. Eine erfolgreiche Mutation in einem GraphQL-Client ist nur der erste Prüfpunkt.

1. Erstellen Sie eine repräsentative Entwicklungsbestellung oder einen Bestellentwurf.
2. Testen Sie einen Wechsel ohne Wertänderung, eine Werterhöhung und eine Wertminderung.
3. Prüfen Sie userErrors nach Begin, nach jeder Mutation zum Vormerken und nach dem Abschluss.
4. Prüfen Sie die berechnete Bestellung vor dem Abschluss.
5. Prüfen Sie den Zahlungseinzug und die Rückerstattung getrennt.
6. Leiten Sie die bearbeitete Bestellung durch das tatsächliche Fulfillment-System.
7. Testen Sie eine archivierte Bestellung, eine ältere Bestellung, sich überschneidende Bearbeitungsversuche und einen Abbruch.
8. Prüfen Sie Shopifys Grenzen der integrierten Bestellbearbeitung, bevor Sie den Zugriff für den Produktivbetrieb einrichten.