Amazon- und eBay-Anbindung in Magento 2: Datenabgleich, Bestell-Sync, Fallstricke

1. Architekturüberblick: Magento als Single Source of Truth

Der erste Entwurfsfehler bei jeder Amazon- und eBay-Anbindung entsteht, bevor eine einzige Zeile Code geschrieben wird: die Frage, welches System für welche Entität die Datenhoheit besitzt, wird nicht explizit beantwortet. Für Produktdaten, Preise und Kategorisierung ist Magento die einzig sinnvolle Quelle der Wahrheit, denn hier laufen Preislogik, Steuerklassen, Kundengruppenpreise und Kataloghierarchie zusammen. Amazon und eBay erhalten in diesem Modell ausschließlich abgeleitete, in ihr jeweiliges Schema transformierte Daten, niemals umgekehrt gepflegte Rückkanäle auf Produktebene.

Bei Bestellungen kehrt sich diese Hierarchie um: Sobald ein Kunde auf Amazon oder eBay kauft, ist der Marketplace das führende System, und Magento übernimmt die Rolle des nachgelagerten Order-Management- und Fulfillment-Systems. Eine Marketplace-Integration, die versucht, Bestellungen bidirektional zu synchronisieren, produziert unweigerlich Konflikte: Wer gewinnt, wenn ein Kunde auf eBay storniert, während in Magento parallel bereits eine Rechnung erstellt wurde? Die einzige praktikable Antwort ist eine klare Einbahnstraße pro Entität, kombiniert mit einem Konfliktprotokoll für die wenigen Fälle, in denen beide Systeme gleichzeitig Zustände ändern.

Diese Aufteilung der Datenhoheit muss technisch abgebildet werden, nicht nur organisatorisch vereinbart. In der Praxis bedeutet das: ein eigenes Modul, das für Produkt- und Preis-Sync ausschließlich lesend auf Magento und schreibend auf die Marketplace-APIs zugreift, sowie ein zweites Modul, das für den Bestell-Sync ausschließlich lesend auf die Marketplace-APIs und schreibend auf Magento zugreift. Diese strikte Richtungstrennung ist der wichtigste Architekturentscheid der gesamten Amazon- und eBay-Anbindung und verhindert die typischen Race Conditions, die bei bidirektionalen Sync-Ansätzen entstehen.

2. Produkt- und Preis-Sync: Feed-Modul und Attribut-Mapping

Der Produkt- und Preis-Sync einer Amazon- und eBay-Anbindung beginnt technisch mit einem Feed-Modul, das ausschließlich über die Service-Contract-Schicht auf den Katalog zugreift, niemals über direkte Collection-Queries oder Resource-Model-Zugriffe. ProductRepositoryInterface::getList() in Kombination mit SearchCriteriaBuilder liefert paginierte Ergebnismengen, die sich auch bei Katalogen mit mehreren zehntausend SKUs ohne Speicherprobleme verarbeiten lassen. Ein generatorbasierter Export, der Seite für Seite liest und sofort weiterreicht, vermeidet, dass der komplette exportierbare Katalog im Arbeitsspeicher gehalten werden muss.

Amazon und eBay verlangen für jede Produktkategorie ein eigenes, teils mehrere hundert Felder umfassendes Attribut-Set, das mit den internen Magento-Attributen nur selten eins-zu-eins übereinstimmt. Ein Kleidungsstück braucht bei Amazon zwingend Felder wie item_type_keyword und bullet_point sowie marktplatzspezifische Größentabellen, während eBay stattdessen Item Specifics mit eigener Kategorie-ID-Struktur erwartet. Ein Attribut-Mapper, der pro Zielkategorie eine Transformationsregel kapselt, entkoppelt diese Anforderungen sauber vom eigentlichen Produktmodell und verhindert, dass Marketplace-spezifische Logik in den Kernkatalog einsickert.

Ebenso zwingend ist eine eigene Mapping-Tabelle zwischen der internen Magento-SKU und den externen Marketplace-Kennungen wie der Amazon ASIN oder der eBay Item-ID. Ohne diese Zuordnungsebene lässt sich weder ein eingehender Bestell-Sync korrekt der richtigen SKU zuordnen, noch ein Datenabgleich beim Bestand zuverlässig durchführen, sobald sich Varianten, Kategorien oder Marketplace-Konfigurationen ändern. Die Mapping-Tabelle wird zur zentralen Übersetzungsschicht der gesamten Amazon- und eBay-Anbindung und sollte pro Kanal auch den Freigabestatus (aktiv, pausiert, abgelehnt) sowie den Zeitpunkt der letzten erfolgreichen Synchronisierung speichern.

<?php

declare(strict_types=1);

namespace Mironsoft\MarketplaceSync\Service\Feed;

use Magento\Catalog\Api\ProductRepositoryInterface;
use Magento\Framework\Api\SearchCriteriaBuilder;
use Mironsoft\MarketplaceSync\Api\MarketplaceMappingRepositoryInterface;
use Mironsoft\MarketplaceSync\Api\AttributeMapperInterface;

/**
 * Builds a normalized product feed for a single marketplace channel.
 * Reads products via the Service Contract layer and maps them to
 * marketplace-specific attribute sets (Amazon category tree / eBay item specifics).
 */
class ProductFeedExportService
{
    public function __construct(
        private readonly ProductRepositoryInterface $productRepository,
        private readonly SearchCriteriaBuilder $searchCriteriaBuilder,
        private readonly MarketplaceMappingRepositoryInterface $mappingRepository,
        private readonly AttributeMapperInterface $attributeMapper,
        private readonly int $pageSize = 200,
    ) {
    }

    /**
     * Streams the product feed for the given marketplace code page by page,
     * so large catalogs never have to be loaded into memory at once.
     *
     * @param string $marketplaceCode e.g. "amazon_de" or "ebay_de"
     * @return \Generator<int, array<string, mixed>>
     */
    public function export(string $marketplaceCode): \Generator
    {
        $currentPage = 1;

        do {
            $searchCriteria = $this->searchCriteriaBuilder
                ->addFilter('marketplace_export', 1, 'eq')
                ->setPageSize($this->pageSize)
                ->setCurrentPage($currentPage)
                ->create();

            $searchResult = $this->productRepository->getList($searchCriteria);

            foreach ($searchResult->getItems() as $product) {
                $mapping = $this->mappingRepository->getByProductAndChannel(
                    (int) $product->getId(),
                    $marketplaceCode
                );

                // Skip products without an approved external mapping,
                // e.g. missing Amazon ASIN or eBay category ID.
                if ($mapping === null || !$mapping->isActive()) {
                    continue;
                }

                yield $this->attributeMapper->mapToChannel($product, $mapping, $marketplaceCode);
            }

            $currentPage++;
        } while ($currentPage <= (int) ceil($searchResult->getTotalCount() / $this->pageSize));
    }
}

3. Bestandsabgleich in Echtzeit: Race Conditions und Multi-Source-Inventory

Ein Bestandsabgleich, der ausschließlich per Cron alle 15 Minuten läuft, funktioniert so lange gut, wie der verfügbare Bestand pro SKU deutlich über den erwarteten Verkäufen im Sync-Intervall liegt. Sobald ein Artikel jedoch nur noch in einstelliger Stückzahl vorrätig ist und gleichzeitig auf dem eigenen Shop, bei Amazon und bei eBay verkauft wird, entsteht ein klassisches Race-Condition-Problem: Zwei Kanäle können im selben 15-Minuten-Fenster denselben letzten verfügbaren Artikel verkaufen, ohne dass der jeweils andere Kanal davon weiß. Das Ergebnis ist Überverkauf, gefolgt von manuellen Stornierungen, die sowohl der Kundenzufriedenheit als auch der Verkäuferbewertung auf beiden Marktplätzen schaden.

Magento Multi Source Inventory bietet mit dem Konzept der Reservations (Magento\InventoryReservationsApi\Api\ReservationBuilderInterface und AppendReservationsInterface) bereits die technische Grundlage, um Bestandsänderungen sofort und ohne Neuberechnung des physischen Lagerbestands zu erfassen. Jede eingehende Marketplace-Bestellung erzeugt eine Reservation, die den Saleable Quantity direkt reduziert, noch bevor die eigentliche Order-Erstellung in Magento abgeschlossen ist. Der Push in Richtung Amazon und eBay sollte deshalb nicht auf den Cron-Zyklus warten, sondern ereignisbasiert ausgelöst werden, sobald sich der Saleable Quantity eines gemappten Produkts ändert.

In der Praxis bewährt sich eine zweistufige Strategie: Ein ereignisbasierter Push bei jeder relevanten Bestandsänderung sorgt für niedrige Latenz bei knappen Beständen, während ein Cron-Sync als Fallback alle wenigen Minuten Abweichungen ausgleicht, die durch fehlgeschlagene Events, API-Ausfälle oder manuelle Korrekturen im Backend entstanden sind. Ein reiner Cron-Ansatz ohne Event-Trigger ist für Artikel mit geringem Bestand strukturell ungeeignet und sollte in keiner produktiven Amazon- und eBay-Anbindung als alleiniger Mechanismus eingesetzt werden.

4. Bestell-Sync: Externe Bestellungen als Magento-Order anlegen

Der Bestell-Sync bildet das Herzstück jeder Amazon- und eBay-Anbindung, weil hier aus einer marktplatzspezifischen Datenstruktur eine vollwertige Magento-Bestellung mit korrekter Steuerberechnung, Versandart und Zahlungsstatus entstehen muss. Der saubere Weg führt über CartManagementInterface::placeOrder() auf einem zuvor programmatisch befüllten Quote, gefolgt vom Zugriff auf die entstandene Order über OrderRepositoryInterface. Ein direktes Schreiben in die Sales-Tabellen unter Umgehung der Quote-zu-Order-Pipeline erzeugt zuverlässig inkonsistente Bestellungen, denen Steuerzeilen, Versandinformationen oder korrekte Totals fehlen.

Externe Bestellstatus lassen sich nicht direkt auf Magento-Status übertragen, weil beide Systeme unterschiedliche Zustandsmodelle verwenden. Amazons Shipped, Unshipped und Canceled sowie eBays Active, Completed und Cancelled müssen über eine dedizierte Status-Mapping-Klasse auf Magento-Status wie processing, complete oder canceled abgebildet werden, wobei fulfillment-abhängige Sonderfälle wie Amazon-FBA-Bestellungen (die bei Auslieferung durch Amazon selbst nie eine Versandmeldung aus Magento erhalten) explizit berücksichtigt werden müssen. Ein hartkodiertes if-Konstrukt für diese Zuordnung wird bei jedem neuen Marketplace oder Fulfillment-Modell zum Wartungsproblem, ein konfigurierbares Mapping in einer eigenen Tabelle dagegen nicht.

Wichtig ist außerdem Idempotenz auf Ebene der externen Bestellnummer: Sowohl Amazon-Benachrichtigungen als auch eBay-Notifications können durch Netzwerkprobleme oder erneutes Ausliefern derselben Nachricht mehrfach eintreffen. Der Import-Service muss vor jeder Order-Erstellung prüfen, ob die externe Bestellnummer bereits verarbeitet wurde, und darf im Wiederholungsfall keine zweite Magento-Bestellung erzeugen. Diese Prüfung gehört in dieselbe Transaktion wie das Anlegen des Sync-Log-Eintrags, um Race Conditions bei parallel laufenden Consumer-Instanzen auszuschließen.

<?php

declare(strict_types=1);

namespace Mironsoft\MarketplaceSync\Service\Order;

use Magento\Quote\Api\CartManagementInterface;
use Magento\Sales\Api\OrderManagementInterface;
use Magento\Sales\Api\OrderRepositoryInterface;
use Mironsoft\MarketplaceSync\Api\Data\ExternalOrderInterface;
use Mironsoft\MarketplaceSync\Model\Order\StatusMapper;
use Mironsoft\MarketplaceSync\Model\Order\SyncLogRepository;
use Psr\Log\LoggerInterface;

/**
 * Creates a Magento sales order from a normalized external order DTO
 * (Amazon SP-API order or eBay Trading API order, already mapped
 * to a marketplace-agnostic structure upstream by a QuoteBuilder).
 */
class MarketplaceOrderImportService
{
    public function __construct(
        private readonly CartManagementInterface $cartManagement,
        private readonly OrderRepositoryInterface $orderRepository,
        private readonly OrderManagementInterface $orderManagement,
        private readonly StatusMapper $statusMapper,
        private readonly SyncLogRepository $syncLogRepository,
        private readonly LoggerInterface $logger,
    ) {
    }

    /**
     * Imports a single external order. Returns the created Magento order ID
     * or null if the order was already imported (idempotent by external order number).
     *
     * @param ExternalOrderInterface $externalOrder
     * @return int|null
     * @throws \Magento\Framework\Exception\LocalizedException
     */
    public function import(ExternalOrderInterface $externalOrder): ?int
    {
        if ($this->syncLogRepository->isAlreadyImported($externalOrder->getExternalOrderNumber())) {
            $this->logger->info(sprintf(
                'Marketplace order %s already imported, skipping.',
                $externalOrder->getExternalOrderNumber()
            ));

            return null;
        }

        // The quote is built from the external order lines beforehand
        // by a dedicated QuoteBuilder that resolves SKUs via the mapping table.
        $quoteId = $externalOrder->getPreparedQuoteId();
        $orderId = (int) $this->cartManagement->placeOrder($quoteId);

        $order = $this->orderRepository->get($orderId);
        $order->setData('external_order_number', $externalOrder->getExternalOrderNumber());
        $order->setData('marketplace_channel', $externalOrder->getMarketplaceCode());

        $mappedStatus = $this->statusMapper->mapExternalStatus(
            $externalOrder->getMarketplaceCode(),
            $externalOrder->getExternalStatus()
        );
        $order->setStatus($mappedStatus);

        $this->orderRepository->save($order);
        $this->syncLogRepository->logSuccess($externalOrder->getExternalOrderNumber(), $orderId);

        return $orderId;
    }
}

5. Queue-basierte Architektur statt synchronem Import

Ein synchroner Import, bei dem ein Cron-Job für jede neue Marketplace-Bestellung direkt und blockierend die komplette Order-Erstellung durchführt, hat einen entscheidenden Konstruktionsfehler: Ein einzelner fehlerhafter Datensatz, etwa eine Bestellung mit einer nicht gemappten SKU, kann den gesamten Batch blockieren oder zumindest alle nachfolgenden Bestellungen im selben Lauf verzögern. Für eine belastbare Amazon- und eBay-Anbindung ist deshalb eine Queue-basierte Architektur mit Magentos Message-Queue-Framework (RabbitMQ als Standard-Broker) die richtige Wahl.

Ein eigenes Topic wie mironsoft.marketplace.order.imported nimmt eingehende, bereits normalisierte externe Bestellungen entgegen, sobald sie durch einen leichten Producer aus der Amazon- oder eBay-API abgeholt wurden. Ein dedizierter Consumer, der Magento\Framework\MessageQueue\ConsumerInterface implementiert, übernimmt die eigentliche, potenziell fehleranfällige Order-Erstellung. Schlägt die Verarbeitung einer einzelnen Nachricht fehl, bleiben alle anderen Nachrichten in der Queue davon unberührt, und die fehlgeschlagene Nachricht kann gezielt in eine Retry-Queue oder Dead-Letter-Queue verschoben werden.

Diese Entkopplung bringt auch operative Vorteile: Die Anzahl paralleler Consumer-Prozesse lässt sich unabhängig von der API-Abholrate skalieren, und ein Ausfall der Amazon SP-API oder der eBay Trading API blockiert nicht den restlichen Sync-Betrieb, weil bereits abgeholte Nachrichten weiterhin aus der Queue verarbeitet werden können. Für eine produktionsreife Message-Queue-Konfiguration braucht es drei zusammenspielende Deklarationen: das Topic in communication.xml, die Exchange-Bindung in queue_topology.xml und die Consumer-Definition in consumers.xml.

<!-- app/code/Mironsoft/MarketplaceSync/etc/communication.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/communication.xsd">
    <topic name="mironsoft.marketplace.order.imported" schema="Mironsoft\MarketplaceSync\Api\Data\ExternalOrderInterface"/>
</config>

<!-- app/code/Mironsoft/MarketplaceSync/etc/queue_topology.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/queue_topology.xsd">
    <exchange name="mironsoft.marketplace" type="topic" connection="amqp">
        <binding id="marketplaceOrderBinding"
                 topic="mironsoft.marketplace.order.imported"
                 destinationType="queue"
                 destination="mironsoft.marketplace.order.import"/>
    </exchange>
</config>

<!-- app/code/Mironsoft/MarketplaceSync/etc/consumers.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/consumers.xsd">
    <consumer name="mironsoft.marketplace.order.import"
              queue="mironsoft.marketplace.order.import"
              connection="amqp"
              handler="Mironsoft\MarketplaceSync\Model\Queue\OrderImportConsumer::process"
              maxMessages="500"/>
</config>

6. Rate Limits und Backoff-Strategien bei Amazon SP-API und eBay Trading API

Sowohl die Amazon SP-API als auch die eBay Trading API begrenzen die Anzahl zulässiger Requests nach dem Token-Bucket-Prinzip: Ein Kontingent an Tokens füllt sich kontinuierlich mit einer festen Rate wieder auf, und jeder Request verbraucht ein Token. Ist das Kontingent erschöpft, antwortet die API mit HTTP 429 (Too Many Requests) beziehungsweise einer marktplatzspezifischen Fehlermeldung, bis wieder Tokens verfügbar sind. Eine Amazon- und eBay-Anbindung, die Requests ohne Rücksicht auf dieses Kontingent feuert, produziert unter Last systematische Fehlversuche statt eines stabilen Datenabgleichs.

Die richtige Reaktion auf eine 429-Antwort ist niemals ein sofortiger erneuter Versuch, sondern exponentielles Backoff: Die Wartezeit zwischen Wiederholungsversuchen verdoppelt sich nach jedem weiteren Fehlschlag, kombiniert mit einer Obergrenze für die maximale Anzahl an Versuchen. Ohne diese Begrenzung riskiert ein Backoff-Mechanismus, in Extremfällen selbst zur Ursache einer Endlosschleife zu werden, wenn ein struktureller Fehler statt eines temporären Rate-Limit-Problems vorliegt.

Da Amazon und eBay unterschiedliche Limits, Zeitfenster und Header-Formate für Rate-Limit-Informationen verwenden, empfiehlt sich ein zentraler API-Client pro Marketplace, der den aktuellen Token-Stand selbst nachverfolgt, statt sich ausschließlich auf reaktive 429-Behandlung zu verlassen. Ein solcher Client kann proaktiv drosseln, bevor die API überhaupt antwortet, was die Zahl unnötiger Fehlversuche im laufenden Bestell-Sync und Datenabgleich spürbar reduziert.

<?php

declare(strict_types=1);

namespace Mironsoft\MarketplaceSync\Service\Api;

use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\RequestException;
use Psr\Log\LoggerInterface;

/**
 * Central API client wrapper with per-marketplace rate-limit tracking
 * and exponential backoff for HTTP 429 / 503 responses.
 */
class RateLimitedApiClient
{
    private const int MAX_RETRIES = 5;
    private const float INITIAL_BACKOFF_SECONDS = 1.0;

    public function __construct(
        private readonly ClientInterface $httpClient,
        private readonly RateLimitTrackerInterface $rateLimitTracker,
        private readonly LoggerInterface $logger,
        private readonly string $marketplaceCode,
    ) {
    }

    /**
     * Executes an HTTP request against the marketplace API, honoring the
     * locally tracked token bucket and retrying with exponential backoff
     * on 429 (Too Many Requests) or 503 responses.
     *
     * @param string $method
     * @param string $uri
     * @param array<string, mixed> $options
     * @return array<string, mixed>
     * @throws \RuntimeException
     */
    public function request(string $method, string $uri, array $options = []): array
    {
        $this->rateLimitTracker->waitForToken($this->marketplaceCode);

        $attempt = 0;
        $backoff = self::INITIAL_BACKOFF_SECONDS;

        while (true) {
            try {
                $response = $this->httpClient->request($method, $uri, $options);
                $this->rateLimitTracker->recordSuccess($this->marketplaceCode, $response->getHeaders());

                return json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
            } catch (RequestException $exception) {
                $statusCode = $exception->getResponse()?->getStatusCode() ?? 0;

                if (!in_array($statusCode, [429, 503], true) || $attempt >= self::MAX_RETRIES) {
                    throw new \RuntimeException(
                        sprintf('Marketplace API call failed after %d attempts: %s', $attempt, $exception->getMessage()),
                        previous: $exception
                    );
                }

                $this->logger->warning(sprintf(
                    '[%s] Rate limited (HTTP %d), retrying in %.1fs (attempt %d)',
                    $this->marketplaceCode,
                    $statusCode,
                    $backoff,
                    $attempt + 1
                ));

                usleep((int) ($backoff * 1_000_000));
                $backoff *= 2;
                $attempt++;
            }
        }
    }
}

7. Notification-basierte Sync statt reinem Polling

Reines Polling, bei dem ein Cron-Job in festen Intervallen bei Amazon oder eBay nach neuen Bestellungen fragt, erzeugt selbst bei kurzen Intervallen eine strukturelle Verzögerung zwischen Kaufzeitpunkt und Sichtbarkeit in Magento. Für zeitkritische Prozesse wie Same-Day-Fulfillment oder automatisierte Lagerbenachrichtigungen ist diese Verzögerung inakzeptabel. Amazon bietet über SNS-Benachrichtigungen (Simple Notification Service) und eBay über eigene Platform Notifications einen ereignisbasierten Mechanismus, der eine neue Bestellung nahezu in Echtzeit an einen registrierten Endpunkt meldet.

Der Endpunkt, der diese Benachrichtigungen entgegennimmt, sollte selbst keine synchrone Verarbeitung durchführen, sondern die eingehende Payload lediglich validieren, in eine normalisierte Struktur überführen und an das in Abschnitt 5 beschriebene Queue-Topic weiterreichen. Diese Entkopplung stellt sicher, dass ein kurzzeitiger Ausfall des Magento-Consumers nicht dazu führt, dass Amazon oder eBay die Notification-Zustellung nach mehreren fehlgeschlagenen Versuchen endgültig einstellt.

Notifications ersetzen den Cron-Sync jedoch nicht vollständig, sondern ergänzen ihn: Da Zustellgarantien bei Webhook-basierten Systemen praktisch nie hundertprozentig sind, bleibt ein Cron-Job als Fallback nötig, der in größeren Intervallen, etwa stündlich, gezielt nach Bestellungen sucht, die noch keinen entsprechenden Sync-Log-Eintrag haben. Diese Kombination aus Notification-Trigger für niedrige Latenz und Cron-Fallback für Zustellsicherheit ist der robusteste Ansatz für den Bestell-Sync in einer produktiven Amazon- und eBay-Anbindung.

{
  "notificationType": "ORDER_STATUS_CHANGE",
  "marketplace": "amazon",
  "eventTime": "2026-07-23T09:14:32Z",
  "payload": {
    "amazonOrderId": "302-1234567-7654321",
    "orderStatus": "Shipped",
    "purchaseDate": "2026-07-21T15:03:11Z",
    "salesChannel": "Amazon.de",
    "fulfillmentChannel": "MFN",
    "orderTotal": {
      "currencyCode": "EUR",
      "amount": "89.90"
    },
    "orderItems": [
      {
        "sellerSku": "MS-7742-BLK",
        "asin": "B0CXYZ1234",
        "quantityOrdered": 2,
        "itemPrice": { "currencyCode": "EUR", "amount": "39.95" }
      }
    ]
  }
}

8. Steuer- und Währungsfallstricke bei grenzüberschreitendem Handel

Die Umsatzsteuerbehandlung einer Marketplace-Bestellung hängt maßgeblich vom Fulfillment-Modell ab. Bei einer Amazon-FBA-Bestellung (Fulfillment by Amazon) kann Amazon je nach Lagerstandort und One-Stop-Shop-Regelung selbst als Steuerschuldner auftreten (Marketplace Facilitator Tax), während bei einer selbst versendeten Bestellung (Merchant Fulfilled Network beziehungsweise eBay-Versand durch den Händler) der Verkäufer die Steuerpflicht behält. Eine Amazon- und eBay-Anbindung, die für alle Bestellungen dieselbe Steuerklasse und denselben Steuerberechnungs-Workflow in Magento anwendet, ignoriert diesen Unterschied und riskiert doppelte oder fehlende Steuerausweisung.

Ein zweiter, in der Praxis unterschätzter Fallstrick ist die Reihenfolge der Steuerberechnung: Marketplace-Reports weisen Preise häufig bereits inklusive Steuer und auf Ebene der Einzelposition gerundet aus, während Magentos Steuerberechnung standardmäßig auf Bestellebene rundet. Bei Bestellungen mit mehreren Positionen und krummen Steuersätzen entstehen dadurch Rundungsdifferenzen von wenigen Cent zwischen dem, was der Marketplace dem Kunden in Rechnung stellt, und dem, was Magento als Order Total berechnet. Diese Differenzen häufen sich über viele Bestellungen zu einem spürbaren Abgleichsproblem in der Buchhaltung.

Bei Währungsumrechnung kommt hinzu, dass Amazon und eBay in unterschiedlichen Marktplätzen (Amazon.de, Amazon.fr, eBay.co.uk) mit unterschiedlichen Wechselkursen zum Zeitpunkt des Kaufs abrechnen, während Magento in der Regel mit dem zum Import-Zeitpunkt gültigen Kurs arbeitet, wenn keine Fremdwährung im gleichen Store-View konfiguriert ist. Für eine korrekte Buchhaltung sollte der Import-Service den vom Marketplace gemeldeten Originalbetrag und die verwendete Währung stets zusätzlich zum umgerechneten Magento-Betrag im Sync-Log speichern, damit spätere Differenzen nachvollziehbar bleiben, statt in der Steuerberechnung unterzugehen.

9. Konfliktlösung und Monitoring: Sync-Log, Retry-Queue und API-Vergleich

Trotz sorgfältigem Bestandsabgleich und Queue-basiertem Bestell-Sync bleiben Konfliktfälle unvermeidbar: Überverkauf bei gleichzeitigem Verkauf auf mehreren Kanälen, Stornierungen, die nach bereits erstellter Rechnung eintreffen, und Rückerstattungen, die zeitlich versetzt zwischen Marketplace und Magento gemeldet werden. Für jeden dieser Fälle braucht die Amazon- und eBay-Anbindung eine definierte Konfliktstrategie statt einer Ad-hoc-Entscheidung im Einzelfall, zum Beispiel automatische Stornierung des überzähligen Verkaufs mit Kundenbenachrichtigung als Standardregel für Überverkauf.

Eine eigene Sync-Log-Tabelle, die jeden Sync-Vorgang mit externer Referenz, Zeitstempel, Richtung (eingehend/ausgehend), Status und gegebenenfalls Fehlermeldung protokolliert, ist die Grundlage für jedes Monitoring. Fehlgeschlagene Synchronisationen landen zusätzlich in einer Retry-Queue mit begrenzter Wiederholungsanzahl und exponentiellem Backoff, analog zum API-Client aus Abschnitt 6, damit temporäre Ausfälle nicht zu dauerhaft verlorenen Datensätzen werden. Ein Alerting auf Basis dieser Tabelle, etwa bei mehr als einer definierten Anzahl fehlgeschlagener Syncs pro Stunde, verhindert, dass Probleme erst durch Kundenbeschwerden auffallen.

Die beiden Marketplace-APIs unterscheiden sich in mehreren für die Architektur relevanten Punkten deutlich voneinander, was sich direkt auf den Implementierungsaufwand einer Amazon- und eBay-Anbindung auswirkt. Die folgende Übersicht fasst die wichtigsten Unterschiede zusammen, die bei der Priorisierung von Entwicklungsaufwand und Fehlerbehandlung berücksichtigt werden sollten.

10. Zusammenfassung

Eine belastbare Amazon- und eBay-Anbindung steht und fällt mit klar getrennter Datenhoheit pro Entität: Magento führt bei Produkt, Preis und Bestand, der Marketplace führt bei der Bestellung. Ein Feed-Modul auf Basis von ProductRepositoryInterface und ein Mapping-Layer zwischen internen SKUs und externen Marketplace-IDs bilden das Fundament für Datenabgleich und Preis-Sync, während ein Queue-basierter Bestell-Sync verhindert, dass ein einzelner fehlerhafter Datensatz den gesamten Sync-Batch blockiert.

Rate-Limit-Handling mit Token-Bucket-Tracking und exponentiellem Backoff, notification-basierte Sync-Trigger statt reinem Polling sowie eine eigene Sync-Log-Tabelle mit Retry-Queue runden die Architektur ab. Wer diese Bausteine von Anfang an einplant statt sie nachträglich zu ergänzen, vermeidet die typischen Fallstricke bei Überverkauf, Steuerbehandlung und Konfliktlösung, die bei nachträglich zusammengeflickten Marketplace-Integrationen regelmäßig zu Supportaufwand führen.

11. FAQ: Amazon- und eBay-Anbindung in Magento 2