Quick Order in Magento 2: Die Backend-API hinter der SKU-Schnellbestellung

1. Quick Order im B2B-Storefront einordnen

Quick Order ist eine Storefront-Funktion der B2B-Suite, mit der Firmenkunden eine Liste aus SKUs und Mengen direkt eingeben oder einfügen können, statt jedes Produkt einzeln über die Suche oder die Kategorie-Navigation zu finden. Fachlich richtet sich das Feature an Kunden, die genau wissen, was sie bestellen wollen, etwa anhand einer eigenen internen Bestellliste oder eines Preislisten-Exports.

Technisch ist Quick Order keine eigenständige neue API, sondern eine dedizierte Storefront-Oberfläche über derselben Cart-Mutation, die Magento auch für das reguläre Hinzufügen mehrerer Produkte zum Warenkorb verwendet. Der eigentliche Mehrwert von Quick Order liegt also weniger im Backend als in der Kombination aus schneller Eingabemaske, Autovervollständigung und einer Antwortstruktur, die gezielt für viele gleichzeitige Positionen ausgelegt ist.

2. Der Ablauf: von der SKU-Liste zum Warenkorb

Der Ablauf hinter Quick Order lässt sich in drei Schritte gliedern: Zunächst wird die eingegebene Liste aus SKU-Mengen-Paaren an das Backend übertragen, dort erfolgt eine Validierung jeder einzelnen Position gegen Produktkatalog, Preis und Lagerbestand, und abschließend werden alle gültigen Positionen gemeinsam dem aktiven Warenkorb hinzugefügt. Ungültige Positionen blockieren dabei nicht automatisch die gültigen, sondern werden separat zurückgemeldet.

Dieses Verhalten unterscheidet sich bewusst von einem klassischen Formular-Submit mit Alles-oder-nichts-Logik. Bei einer Liste mit fünfzig Positionen, von denen zwei ungültig sind, werden die restlichen achtundvierzig trotzdem in den Warenkorb übernommen, während die beiden fehlerhaften Positionen mit einem konkreten Fehlercode zurückgemeldet werden, sodass der Kunde gezielt nachbessern kann, statt die komplette Eingabe zu wiederholen.

3. Die zugrunde liegende GraphQL-Mutation

Backendseitig läuft eine Quick-Order-Anfrage über dieselbe addProductsToCart-Mutation, die auch für andere Bulk-Warenkorb-Operationen verwendet wird. Sie akzeptiert eine Liste aus Cart-Items mit SKU und Menge und liefert im Antwortobjekt sowohl den aktualisierten Warenkorb als auch eine Liste von user_errors zurück, in der jede fehlgeschlagene Position einzeln mit einem sprechenden Fehlercode aufgeführt wird.

Für eigene Frontend-Implementierungen ist wichtig, diese Antwortstruktur konsequent auszuwerten, statt nur zu prüfen, ob die Mutation insgesamt erfolgreich war. Eine Mutation ohne technischen Fehler kann trotzdem mehrere user_errors enthalten, wenn einzelne Positionen aus fachlichen Gründen nicht übernommen werden konnten, etwa weil eine SKU nicht existiert oder ein Produkt gerade nicht verkäuflich ist.

mutation QuickOrderAddToCart {
  addProductsToCart(
    cartId: "abc123cartid"
    cartItems: [
      { sku: "SKU-1001", quantity: 5 }
      { sku: "SKU-1002", quantity: 12 }
      { sku: "SKU-UNKNOWN", quantity: 3 }
    ]
  ) {
    cart {
      id
      total_quantity
    }
    user_errors {
      code
      message
    }
  }
}

4. Eigene CSV-Upload-Frontends aufbauen

Für einen CSV-Upload, der über die Standard-Quick-Order-Eingabemaske hinausgeht, lässt sich dieselbe Mutation wiederverwenden: Die CSV-Datei wird geparst, in eine Liste aus SKU-Mengen-Paaren überführt und anschließend an addProductsToCart übergeben. Der Vorteil dieses Ansatzes ist, dass keine eigene Validierungslogik dupliziert werden muss, sondern dieselbe serverseitige Prüfung wie bei der Standard-Quick-Order-Eingabe greift.

Bei sehr großen CSV-Dateien mit mehreren hundert oder tausend Zeilen empfiehlt sich, die Datei nicht als eine einzige Mutation zu übertragen, sondern in Chargen von beispielsweise fünfzig bis hundert Positionen aufzuteilen. Das begrenzt sowohl die Laufzeit eines einzelnen Requests als auch das Risiko, dass ein einzelner sehr großer Request an einem Timeout in der Infrastruktur zwischen Frontend und Magento scheitert.

<?php

declare(strict_types=1);

namespace Mironsoft\QuickOrderExtension\Model;

/**
 * Teilt eine große Liste aus SKU-Mengen-Paaren in verarbeitbare Chargen auf,
 * um addProductsToCart nicht mit tausenden Positionen in einem Aufruf zu belasten.
 */
class SkuBatchSplitter
{
    private const DEFAULT_BATCH_SIZE = 75;

    /**
     * @param array<int, array{sku: string, qty: float}> $items
     * @param int $batchSize
     * @return array<int, array<int, array{sku: string, qty: float}>>
     */
    public function split(array $items, int $batchSize = self::DEFAULT_BATCH_SIZE): array
    {
        return array_chunk($items, $batchSize);
    }
}

5. Serverseitige SKU-Validierung im Detail

Die Validierung einer einzelnen SKU im Backend prüft mehrere Dinge nacheinander: Existiert die SKU überhaupt im Produktkatalog, ist das Produkt im aktuellen Store sichtbar und aktiviert, und im Fall eines konfigurierbaren Produkts, verweist die eingegebene SKU auf eine konkrete Kindvariante oder auf das übergeordnete, nicht direkt bestellbare Elternprodukt. Letzteres ist eine häufige Fehlerquelle bei eigenen Implementierungen, weil Kunden aus Preislisten oft die Eltern-SKU statt der Varianten-SKU kopieren.

Für eigene Erweiterungen, die zusätzliche SKU-Normalisierung benötigen, etwa Groß- und Kleinschreibung zu ignorieren oder führende Nullen zu entfernen, bietet sich eine Vorverarbeitung der eingegebenen Liste vor dem eigentlichen Mutation-Aufruf an, statt die Normalisierung tief in der Kernvalidierung zu verändern, was mit zukünftigen B2B-Suite-Updates kollidieren könnte.

6. Fehlerbehandlung: Teilerfolg sauber kommunizieren

Weil eine Quick-Order-Anfrage typischerweise aus vielen Positionen besteht, ist die größte Herausforderung für ein eigenes Frontend nicht die einzelne Fehlermeldung, sondern die verständliche Darstellung eines Teilerfolgs. Ein Nutzer, der eine CSV mit hundert Zeilen hochlädt und nur die Meldung erhält, dass drei Fehler aufgetreten sind, kann ohne Zuordnung zur ursprünglichen Zeile kaum sinnvoll reagieren.

Die robuste Lösung ist, beim Aufbau der cartItems-Liste den Zeilenindex der ursprünglichen CSV mitzuführen, etwa als eigenes Feld im internen Datenmodell, und die zurückgemeldeten user_errors anhand der betroffenen SKU wieder der passenden Ursprungszeile zuzuordnen. So kann das Frontend dem Nutzer exakt zeigen, welche Zeile korrigiert werden muss, statt nur eine allgemeine Fehlerzahl anzuzeigen.

7. Lagerbestand und Backorders bei der Prüfung

Die Bestandsprüfung einer Quick-Order-Position läuft über dieselbe MSI-Logik wie an anderer Stelle im Shop und berücksichtigt die aggregierte verkaufsfähige Menge über alle zugewiesenen Sources hinweg, nicht den Bestand einer einzelnen Quelle isoliert. Ob eine Menge oberhalb des aktuellen Bestands zu einem harten Fehler oder zu einer akzeptierten Backorder-Position führt, hängt von der Backorder-Konfiguration des jeweiligen Produkts ab.

Für eigene Frontends ist relevant, dass eine erfolgreiche Backorder-Position keinen Fehler in user_errors erzeugt, sich aber im Warenkorb typischerweise durch einen zusätzlichen Hinweis zur Lieferzeit unterscheidet. Wer eine eigene Zusammenfassung nach dem Quick-Order-Vorgang anzeigen will, sollte diesen Fall separat behandeln, statt jede Position ohne expliziten Fehler unterschiedslos als vollständig verfügbar darzustellen.

8. Quick Order per Plugin gezielt einschränken

Für manche Kataloge ist sinnvoll, bestimmte Produkttypen von der Schnellbestellung auszuschließen, etwa virtuelle oder downloadbare Produkte, die im normalen Bestellprozess zusätzliche Angaben erfordern, die eine reine SKU-Mengen-Eingabe nicht abbilden kann. Dafür bietet sich ein Plugin auf dem Resolver oder Service an, der die einzelne Position validiert, mit einer zusätzlichen Prüfung des Produkttyps vor der eigentlichen Bestands- und Preisvalidierung.

Ebenso lässt sich über denselben Mechanismus eine Mindestbestellmenge pro SKU durchsetzen, die über die reguläre Produktkonfiguration hinausgeht, etwa weil bestimmte Artikel ausschließlich in Paletten- statt Einzelmengen über Quick Order bestellt werden dürfen. Wichtig ist, denselben Fehlerkanal wie die Standardvalidierung zu nutzen, damit sich eigene und Standard-Fehlercodes im Frontend einheitlich behandeln lassen.

9. Performance bei großen SKU-Listen

Bei einer Quick-Order-Anfrage mit vielen Positionen ist die größte Performance-Falle, für jede Position einzeln und nacheinander Preis- und Bestandsdaten aus der Datenbank zu laden, statt die zugrunde liegenden Repositories mit ihren Bulk-Lademethoden zu nutzen. Wer eine eigene Erweiterung der Validierung baut, sollte konsequent auf Methoden setzen, die mehrere SKUs in einem einzigen Aufruf laden, statt die Anzahl der Datenbankabfragen linear mit der Listenlänge wachsen zu lassen.

Für sehr hohe Volumina, etwa eine automatisierte nächtliche Bestellung aus einem angebundenen ERP-System, lohnt sich außerdem, denselben Validierungspfad wie im interaktiven Quick-Order-Formular zu verwenden, aber außerhalb der synchronen Request-Antwort-Zeit eines Nutzers auszuführen, etwa über einen Message-Queue-Consumer, damit große Bestellmengen den regulären Storefront-Traffic nicht ausbremsen.

10. Zusammenfassung

11. FAQ: Quick Order Backend-API