Mirakl-Steuermodus in weclapp: Wie die Vier-Quadranten-Logik Netto-Brutto- und Versandsteuer-Fehler verhindert
Kurz gesagt: In der Mirakl-Auftrags-API (Endpunkt OR11) legt jeder Marktplatz selbst fest, ob Einzel- und Versandpreise netto im Modus TAX_EXCLUDED oder brutto im Modus TAX_INCLUDED geliefert werden, während in weclapp das Präfix deines Vertriebswegs (NET oder GROSS) über die Preisinterpretation entscheidet. Ohne eine explizite Vier-Quadranten-Steuerlogik mit Prüfung des Steuer-Arrays, Versandsteuer-Trennung und Brutto-Summenabgleich weichen Ausgangsrechnungen um bis zu 19 Prozent vom gezahlten Käuferbetrag ab und blockieren anschließend den automatischen MT940-Zahlungsabgleich.
Dieser technische Praxis-Leitfaden richtet sich an E-Commerce-Verantwortliche, Buchhaltungs-Teams und Systemarchitekt:innen, die einen oder mehrere Mirakl-Marktplätze an weclapp anbinden. Während unsere Überblicksseite Mirakl-Marktplätze an weclapp anbinden den Gesamtablauf beschreibt, zerlegen wir hier die genaue Steuer- und Betragsmechanik zwischen dem Mirakl-Auftragsobjekt (OR11) und dem weclapp-Verkaufsauftrag (salesOrder) – von Mischwarenkörben über leere Steuer-Arrays bis zum abschließenden Offene-Posten-Ausgleich.

Das Wichtigste in Kürze
-
Zwei unabhängige Systeme treffen aufeinander. Der Mirakl-Marktplatz bestimmt über
order_tax_mode(TAX_INCLUDEDoderTAX_EXCLUDED), was im Feldprice_unitsteht; dein weclapp-Vertriebsweg (GROSS*oderNET*) bestimmt unabhängig davon, wie weclapp den übergebenenunitPriceweiterrechnet. -
Vier Quadranten entscheiden über
none,addoderdeduct. Nur wenn beide Seiten übereinstimmen, darf der Preis unverändert durchgereicht werden; bei Abweichung muss je Position und Versandzeile gezielt Umsatzsteuer aufgeschlagen oder herausgerechnet werden. -
Ein leeres
taxes: []-Array ist kein Steuersatz von0 %. Manche Marktplätze deklarierenTAX_EXCLUDED, senden aber keine Steuerobjekte und übergeben inprice_unitbereits den gezahlten Bruttobetrag – ein Schutz-Guard (CONVERSION_SKIP_NO_TAX_DATA) verhindert hier falsche Aufschläge ebenso wie eine Verwechslung mit steuerfreien0,0 %-Lieferungen (CONVERSION_SKIP_ZERO_RATE). -
Versandkosten stecken in Mirakl bereits im Positions-
total_price. Sowohl bei der Versandsteuer (shipping_taxes) als auch beim Summenabgleich müssen Warenwert und Versand sauber getrennt werden, damit weder Versandsteuer doppelt abgezogen noch ein Schein-Delta gemeldet wird. -
Ein einziger Cent- oder Quadrantenfehler sprengt später den MT940-OP-Ausgleich. Weil die Kontoauszugserkennung in weclapp neben der Rechnungsnummer zwingend den exakten Rechnungsbetrag prüft, ist ein abgestimmter Brutto-Rechnungsbetrag (
reconcile_order_payload_totals) die Voraussetzung für das automatische Schließen deiner offenen Posten.
1. Warum laufen Mirakl-Bestellungen und weclapp-Vertriebswege steuerlich so leicht auseinander?
Wer seinen ersten Mirakl-Marktplatz erfolgreich an weclapp angebunden hat, geht beim zweiten oder dritten Kanal oft selbstverständlich davon aus, dass die Auftrags-JSON-Struktur aus dem Endpunkt OR11 steuerlich identisch aufgebaut ist. Genau diese Annahme verursacht in der Praxis einige der teuersten Buchhaltungsfehler im Multichannel-Handel: Das Datenmodell von Mirakl ist zwar standardisiert, doch den Steuermodus legt jeder Marktplatz-Betreiber für seine Plattform selbst fest.
Im Kopffeld order_tax_mode liefert Mirakl einen von zwei Werten aus. Steht dort TAX_INCLUDED – wie wir es im Produktivbetrieb unter anderem bei klassischen Endkunden-Plattformen wie Shop Apotheke, zooplus oder MediaMarktSaturn sehen –, enthalten der Positions-Einzelpreis price_unit und der Versandpreis shipping_price bereits die gesetzliche Umsatzsteuer. Steht dort hingegen TAX_EXCLUDED – typisch für B2B-Plattformen wie hygi.de, aber ebenso auf einzelnen Einzelhandels-Plattformen wie Fressnapf anzutreffen –, deklariert der Marktplatz die Preisfelder als Nettowerte und liefert die Umsatzsteuer separat in den Arrays order_lines[].taxes sowie order_lines[].shipping_taxes mit.
Auf der Gegenseite kennt der weclapp-Verkaufsauftrag (salesOrder) beim API-Import mit manualUnitPrice: true kein eigenes Feld namens order_tax_mode. Ob weclapp den übergebenen unitPrice in orderItems und shippingCostItems als Brutto- oder als Nettopreis interpretiert, hängt ausschließlich an der Konfiguration deines gewählten Vertriebswegs (salesChannel): Beginnt der technische Schlüssel des Vertriebswegs mit NET (zum Beispiel NET1 für B2B-Marktplätze), behandelt weclapp jeden importierten Einzelpreis als Nettopreis und schlägt die Umsatzsteuer gemäß Steuermatrix oben auf; bei allen Brutto-Vertriebswegen (GROSS*) rechnet weclapp die Umsatzsteuer aus dem übergebenen Preis heraus.
Prüft ein Integrationsskript nur eine dieser beiden Seiten – oder reicht es price_unit ungeprüft eins zu eins durch –, entstehen sofort drei klassische Fehlerbilder: Trifft TAX_EXCLUDED ungeprüft auf einen GROSS*-Kanal, fakturiert weclapp den Nettopreis als Endkunden-Bruttopreis und verschenkt bei 19 Prozent Regelsteuersatz knapp ein Sechstel des Umsatzes. Trifft TAX_INCLUDED ungeprüft auf einen NET*-Kanal, schlägt weclapp nochmals 19 Prozent Umsatzsteuer auf den bereits versteuerten Endpreis auf. Und zieht ein älteres Skript auf NET*-Kanälen pauschal shipping_taxes vom shipping_price ab, ohne zu prüfen, ob TAX_EXCLUDED bereits netto liefert, entsteht auf jeder einzelnen Bestellung eine doppelte Versandsteuer-Kürzung. Das ersetzt keine Steuerberatung.
Fazit: Eine verlässliche Mirakl-Integration darf niemals starr vom Vertriebsweg auf das Preisformat schließen, sondern muss bei jedem Auftrag order_tax_mode und salesChannel gemeinsam auswerten.
2. Wie rechnet die Vier-Quadranten-Steuerlogik jeden Fall zwischen TAX_INCLUDED, TAX_EXCLUDED, GROSS und NET um?
In unserer Plattform Mirakl 4 weclapp löst die Funktion needs_tax_conversion(sales_channel, order_tax_mode) diesen Konflikt deterministisch in vier klar abgegrenzten Quadranten auf. Sie stellt zwei einfache boolesche Fragen nebeneinander: Erwartet weclapp auf diesem Vertriebsweg Nettopreise (sales_channel.startswith("NET")), und liefert Mirakl in diesem Auftrag Nettopreise (order_tax_mode == "TAX_EXCLUDED")?
Stimmen beide Antworten überein, lautet die Umrechnungsrichtung "none" (CONVERSION_NOT_NEEDED) – beide Systeme sprechen bereits dieselbe Preissprache. Weichen die Antworten voneinander ab, ergibt sich zwingend entweder die Richtung "add" (Mirakl liefert netto, weclapp erwartet brutto auf einem GROSS*-Kanal) oder die Richtung "deduct" (Mirakl liefert brutto, weclapp erwartet netto auf einem NET*-Kanal). Für substantiierte Steuersätze wendet apply_tax_conversion anschließend pro Auftragszeile entweder die Aufschlagsformel price * (1 + tax_rate / 100) oder die Herausrechnungsformel price / (1 + tax_rate / 100) an.
| Quadrant | Mirakl order_tax_mode
|
weclapp salesChannel
|
Richtung | Fiktives Beispiel (Käuferzahlung 119,00 € inkl. 19 % USt) |
|---|---|---|---|---|
| Q1: Brutto auf Brutto | TAX_INCLUDED |
GROSS* |
none |
Mirakl sendet 119.00; weclapp erhält unitPrice: "119.00" (100,00 € netto + 19,00 € USt) |
| Q2: Netto auf Netto | TAX_EXCLUDED |
NET* |
none |
Mirakl sendet 100.00 + 19.00 Steuer; weclapp erhält unitPrice: "100.00" und addiert 19 % zu 119,00 € |
| Q3: Netto auf Brutto | TAX_EXCLUDED |
GROSS* |
add |
Mirakl sendet 100.00 + rate: 19.0; Umrechnung 100 * 1,19 ergibt unitPrice: "119.00" in weclapp |
| Q4: Brutto auf Netto | TAX_INCLUDED |
NET* |
deduct |
Mirakl sendet 119.00 + rate: 19.0; Umrechnung 119 / 1,19 ergibt unitPrice: "100.00" in weclapp |
Schauen wir uns die vier fiktiven Rechenwege im Detail an, wenn eine Käufer:in im Inland einen Artikel im Gesamtwert von 119,00 € brutto (100,00 € netto zuzüglich 19,00 € Umsatzsteuer nach § 12 Abs. 1 UStG) zuzüglich 5,95 € brutto Versandkosten (5,00 € netto plus 0,95 € Versandsteuer, Gesamtzahlung 124,95 €) bestellt: In Quadrant 1 (TAX_INCLUDED auf GROSS1) übergibt Mirakl price_unit: 119.00 und shipping_price: 5.95; beide Werte fließen unverändert nach weclapp und ergeben exakt 124,95 € Rechnungsbetrag. In Quadrant 2 (TAX_EXCLUDED auf NET1, etwa im B2B-Betriebsbedarf) liefert Mirakl price_unit: 100.00 und shipping_price: 5.00 neben shipping_taxes: [{"rate": 19.0, "amount": 0.95}]; weil die Richtung "none" lautet, bleiben sowohl "100.00" als auch "5.00" unangetastet, und weclapp berechnet daraus sauber 105,00 € netto plus 19,95 € Umsatzsteuer gleich 124,95 € brutto.
In Quadrant 3 (TAX_EXCLUDED auf GROSS1) würde ein ungeschützter Import fälschlich 100,00 € und 5,00 € als Bruttopreise in weclapp anlegen (Rechnung über 105,00 € statt 124,95 €, also 19,95 € Fehlbetrag). Mit der Richtung "add" rechnet die Konvertierung die Position über rate: 19.0 auf "119.00" hoch und addiert bei den Versandkosten die ausgewiesene Versandsteuer 0.95 auf 5.00 zu "5.95". Spiegelbildlich dividiert Quadrant 4 (TAX_INCLUDED auf NET1) den Bruttopreis 119.00 durch 1.19 auf "100.00" herunter und zieht bei den Versandkosten den ausgewiesenen Steuerbetrag 0.95 von 5.95 auf "5.00" ab, sodass weclapp auf dem Nettokanal exakt wieder bei 124,95 € brutto landet. Das ersetzt keine Steuerberatung.
Fazit: Über alle vier Quadranten hinweg sorgt die gerichtete Umrechnung von Positions- und Versandpreisen dafür, dass in weclapp am Ende immer exakt derselbe Brutto-Zahlbetrag steht, den die Käufer:in auf dem Marktplatz bezahlt hat.
3. Wie verhält sich die Steuerlogik bei Mischwarenkörben (7 % + 19 %) und Versandkosten?
Besonders fehleranfällig wird die Umrechnung, sobald in einer einzigen Mirakl-Bestellung unterschiedliche Steuersätze aufeinandertreffen – etwa im Heimtier-, Lebensmittel-, Drogerie- oder Buchhandel, wo ermäßigt besteuerte Produkte mit 7 Prozent in Deutschland (§ 12 Abs. 2 UStG in Verbindung mit Anlage 2 UStG; in Österreich je nach Warengruppe 10 oder 13 Prozent) gemeinsam mit 19-Prozent-Zubehörartikeln im selben Paket liegen. Eine pauschale Umrechnung auf Kopfebene mit einem festen Steuersatz von 19 Prozent würde jede ermäßigte Position sofort verfälschen.
Deshalb liest resolve_line_tax_rate(line) den Steuersatz in map_mirakl_order_to_weclapp_order_payload strikt zeilenweise aus dem Array line["taxes"] jeder einzelnen Bestellposition aus. Rechnen wir einen fiktiven Mischwarenkorb im Modus TAX_EXCLUDED auf einem weclapp-Bruttokanal (GROSS2, Quadrant 3) durch: Position 1 umfasst zwei Säcke Tierfutter zu je price_unit: 25.00 netto mit taxes: [{"rate": 7.0, "amount": 3.50}], Position 2 eine Hundeleine zu price_unit: 40.00 netto mit taxes: [{"rate": 19.0, "amount": 7.60}], dazu fallen auf Kopfebene shipping_price: 5.00 netto Versandkosten an, deren Steuerbeträge in order_lines[].shipping_taxes in Summe 0.95 betragen.
Bei der Konvertierung erhält Position 1 über ihren 7-Prozent-Satz den Brutto-Einzelpreis 25.00 * 1.07 = "26.75" (mal 2 ergibt 53,50 € brutto), während Position 2 im selben Auftrag über ihren 19-Prozent-Satz auf 40.00 * 1.19 = "47.60" umgerechnet wird. Für die Versandposition summiert resolve_shipping_tax_total(order_obj) nicht irgendeinen geratenen Prozentsatz, sondern exakt die vom Marktplatz über alle Auftragszeilen gemeldeten Steuerbeträge aus shipping_taxes[].amount (hier 0.95) und addiert diesen Betrag in Richtung "add" direkt zum Netto-Versandpreis 5.00 auf unitPrice: "5.95" (beziehungsweise zieht ihn in Richtung "deduct" exakt ab). Damit stimmt die Gesamtsumme aus 53,50 € plus 47,60 € plus 5,95 € gleich 107,05 € auf den Cent, vorausgesetzt, deine Artikelkategorien und Versandkosten-Steuerregeln in der weclapp-Steuermatrix bilden dieselben Steuersätze sauber ab (Umsatzsteuer bei Marktplatzverkäufen in weclapp).
Eine zweite Mirakl-Eigenheit betrifft das Zusammenspiel von total_price und shipping_price bei der Summenkontrolle: Über alle produktiv angebundenen Mirakl-Marktplätze hinweg enthält das Feld line["total_price"] einer Auftragsposition bereits den anteiligen line["shipping_price"] dieser Zeile, und das Kopffeld order["total_price"] entspricht der Summe dieser Zeilen-Gesamtpreise inklusive Versand. Wer zur Gegenprobe alle Zeilen-total_price-Werte addiert und zusätzlich noch einmal order["shipping_price"] obendrauf rechnet, zählt die Versandkosten doppelt und erzeugt bei jeder versandkostenpflichtigen Bestellung einen falschen Abweichungsalarm; unsere Hilfsfunktion _reported_line_amounts zieht deshalb zuerst shipping sauber vom Zeilen-total_price ab, bevor sie Warenwert und Versand getrennt mit ihren jeweiligen Steuerbeträgen bewertet. Das ersetzt keine Steuerberatung.
Fazit: Zeilenweise Steuersatz-Auflösung für Artikel, betragsgenaue Summierung von shipping_taxes und die saubere Herauslösung des Versands aus line["total_price"] halten gemischte Warenkörbe centgenau im Gleichgewicht.
4. Warum schützt der Guard bei leerem taxes: []-Array vor stillen 19-%-Fehlern und Reverse-Charge-Fallen?
In der Theorie liefert jeder Mirakl-Auftrag im Modus TAX_EXCLUDED ein gefülltes taxes-Array mit Steuersatz (rate) und Steuerbetrag (amount). In der Realität produktiver Marktplatz-APIs stießen wir jedoch auf ein hochgefährliches Sonderverhalten: Einzelne Plattformen (darunter bestimmte Retail-Konstellationen wie Fressnapf) kennzeichnen Bestellungen im Kopffeld als order_tax_mode = "TAX_EXCLUDED", senden auf den Positionen aber ein komplett leeres Array "taxes": [] – und schreiben in price_unit bereits den vollen Bruttobetrag, den die Käufer:in an der Kasse bezahlt hat.
Hier entscheidet ein feiner Unterschied im Code über tausende richtige oder falsche Rechnungen: In einer naiven Implementierung liefert eine Hilfsfunktion, die in einem leeren Array keinen Steuersatz findet, häufig standardmäßig die Zahl 0.0 zurück. Auf einem GROSS*-Kanal multipliziert das Skript dann price_unit * (1 + 0.0 / 100) und kommt rein zufällig auf den richtigen Betrag; noch schlimmer ist ein Skript, das bei fehlendem Steuersatz blind mit einem fest einprogrammierten Standardwert von 1.19 multipliziert und dadurch jeden bereits brutto übergebenen Kaufpreis um 19 Prozent überhöht – oder das im Moment einer späteren API-Umstellung des Marktplatzes unkontrolliert umschlägt.
Deshalb trennt resolve_line_tax_rate in unserer Integration streng zwischen zwei fachlich völlig verschiedenen Zuständen: Gibt der Marktplatz gar keine numerische Steueraussage ab ("taxes": [], fehlendes Feld oder ein Objekt wie {"code": "TAXDEFAULT"} ohne numerisches rate; auch Booleans und Strings lehnt _numeric strikt ab), lautet der Rückgabewert None. Meldet der Marktplatz hingegen ausdrücklich einen Steuersatz von null Prozent ("taxes": [{"rate": 0.0, "amount": 0.0}]) – wie er bei steuerfreien innergemeinschaftlichen B2B-Lieferungen beziehungsweise Reverse-Charge-Sachverhalten (§ 4 Nr. 1b, § 13b UStG) oder bei steuerfreien Drittlands-Ausfuhrlieferungen etwa in die Schweiz (§ 4 Nr. 1a UStG) vorkommt –, lautet der Rückgabewert explizit 0.0.
Darauf baut resolve_price_conversion(conversion, declared_tax_rate, tax_rate_fallback) vier eindeutige, im Log nachvollziehbare Entscheidungen auf: Bei CONVERSION_NOT_NEEDED passen Kanal und Modus bereits zusammen; bei CONVERSION_APPLY liegt ein positiver Steuersatz vor und die Umrechnung greift; bei CONVERSION_SKIP_ZERO_RATE wurde ausdrücklich 0.0 % gemeldet, sodass die Umrechnung gewollt eine dokumentierte Null-Operation bleibt; und bei CONVERSION_SKIP_NO_TAX_DATA (deklarierter Modus-Konflikt, aber declared_tax_rate is None) verweigert die Integration jede ungeprüfte Umrechnung, übernimmt den gemeldeten Zahlbetrag unverändert und schreibt eine deutliche Warnung ins Protokoll. Nur wenn ein Marktplatz nachweislich echte Nettopreise ganz ohne taxes-Aufschlüsselung liefert, schaltet ein explizit am Mandanten hinterlegter, streng validierter order_tax_rate_fallback (nur echte Zahlen größer 0 bis 100, der niemals echte Marktplatz-Steuerdaten überschreibt) die Umrechnung gezielt frei. Das ersetzt keine Steuerberatung.
Fazit: Wer „keine Steuerdaten gesendet“ (None) strikt von „steuerfrei mit 0,0 % deklariert“ trennt, verhindert sowohl blinde 1,19-Multiplikationen bei Ausfuhren als auch zufällige Rechenfehler bei leeren taxes-Arrays.
5. Wie greifen der automatische Brutto-Summenabgleich und der MT940-OP-Ausgleich ineinander?
Selbst die beste Konvertierungsformel sollte im Zahlungsverkehr niemals ohne unabhängige Gegenprobe in das ERP schreiben. Deshalb führt map_mirakl_order_to_weclapp_order_payload unmittelbar vor dem Anlegen jedes Auftrags in weclapp die Prüfroutine reconcile_order_payload_totals(order_obj, new_order_payload, sales_channel, user) aus: Sie berechnet auf der einen Seite unabhängig aus den rohen Mirakl-Positionen und Steuerbeträgen, was die Käufer:in brutto bezahlt hat (marketplace_gross), und auf der anderen Seite aus den tatsächlich in orderItems und shippingCostItems eingetragenen unitPrice-Strings, welchen Bruttobetrag weclapp fakturieren wird (weclapp_gross – auf NET*-Kanälen für den Vergleich entsprechend hochgerechnet).
Dabei berücksichtigt die Prüfung auch unvermeidbare kaufmännische Rundungseffekte bei Mehrstück-Positionen: Weil weclapp den Einzelpreis unitPrice mit zwei Nachkommastellen speichert und danach mit quantity multipliziert, kann jede Einheit um bis zu einen halben Cent von einer zeilenweisen Steuerberechnung in Mirakl abweichen. Ein fiktives Beispiel zeigt das sofort: Kauft jemand 3 Packungen eines Artikels zu je 14,90 € netto mit 7 % Umsatzsteuer (14,90 * 1,07 = 15,943 €), wird unitPrice auf "15.94" gerundet; 3 * 15,94 € ergeben in weclapp 47,82 € brutto, während 44,70 € * 1,07 auf Positionsebene in Mirakl gerundet 47,83 € ergeben. Unser Toleranzband nach der Formel round(0.02 + 0.01 * (units + len(lines)), 2) (ORDER_TOTAL_TOLERANCE_BASE = 0.02 zuzüglich ORDER_TOTAL_TOLERANCE_PER_UNIT = 0.01 mal die Summe aller orderItems[].quantity inklusive eventueller Versandposition plus Anzahl der Mirakl-Auftragszeilen) akzeptiert genau diese unvermeidbare Ein-Cent-Rundungsspur, schlägt aber bei jedem echten Steuer- oder Versandfehler (etwa 0,95 € oder 19,00 € Differenz) sofort mit ORDER TOTAL MISMATCH im Monitoring an – und behandelt Sonderkonfigurationen wie deaktivierten Versandkosten-Import (import_shipping_cost_items = False, ausgewiesen unter shipping_excluded) oder den Einkaufspreis-Modus bei eConsignment-Modellen (set_purchase_price_as_sales_price = True, markiert als comparable = False) sauber ohne Fehlalarm.
Warum diese Cent-Präzision über das Wohlbefinden deiner gesamten Finanzbuchhaltung entscheidet, zeigt sich vierzehn Tage später beim Einlesen der Sammelauszahlung: Unser MT940-Konverter erzeugt aus den Mirakl-Transaktionslogs (TL03 bis TL05) für jede Bestellung eine Buchungszeile (:61:) über den auf Mirakl abgerechneten Brutto-Auftragsbetrag (Warenwert plus Versand, getrennt von den COMMISSION-Zeilen) und schreibt deine mindestens sechsstellige weclapp-Rechnungsnummer vorab in den Verwendungszweck (:86:).
Laut offizieller weclapp-Hilfe zur Kontoauszugserkennung gleicht weclapp einen offenen Posten beim Bankimport nur dann automatisch aus, wenn neben der Referenznummer auch der Zahlbetrag exakt mit dem offenen Rechnungsbetrag übereinstimmt (beziehungsweise innerhalb einer vereinbarten Skontofrist liegt). Weicht deine Ausgangsrechnung wegen eines falschen Steuer-Quadranten um 19 Prozent oder wegen doppelt abgezogener Versandsteuer um 95 Cent vom Mirakl-Zahlbetrag ab, bleibt buchstäblich jede einzelne Rechnung auf dem Marktplatz-Verrechnungskonto ungeklärt stehen; wie der vorangereicherte Kontoauszug im Detail aufgebaut ist, liest du in unserem Leitfaden MT940-Kontoauszug anreichern für weclapp: Wie Marktplatz- und PSP-Auszahlungen Offene Posten automatisch schließen sowie auf Marktplatz-Auszahlungen in weclapp abgleichen. Das ersetzt keine Steuerberatung.
Fazit: Der automatische Brutto-Summenabgleich beim Auftragsimport ist das direkte Sicherheitsnetz dafür, dass deine vorangereicherten MT940-Auszahlungsdateien zwei Wochen später alle offenen Posten ohne Handarbeit schließen.
6. Checkliste für das Onboarding eines neuen Mirakl-Kanals und ehrliche Systemgrenzen
Bevor du einen weiteren Mirakl-Marktplatz live auf deinen weclapp-Mandanten schaltest, prüfst du mit deiner Projektleitung und deiner Steuerkanzlei fünf Punkte anhand einer echten Test- oder Pilotbestellung:
-
order_tax_modeundtaxes-Befüllung im rohenOR11-Payload lesen: Prüfe am echten JSON-Auftrag des Marktplatzes, obTAX_INCLUDEDoderTAX_EXCLUDEDgesetzt ist und oborder_lines[].taxessowieshipping_taxesnumerischerate- undamount-Werte liefern. -
Ziel-Vertriebsweg (
GROSS*vs.NET*) je Land festlegen: Trenne mehrere Verkaufs-Länder (etwa DE, AT, CH) konsequent über eigenemirakl_shop_id, eigenen Vertriebsweg und eigenes Verrechnungskonto. -
weclapp-Steuermatrix für Artikel und Versand gegenprüfen: Die Vier-Quadranten-Logik liefert den exakt passenden Brutto- oder Netto-
unitPrice, aber welchen Umsatzsteuersatz und welches Erlöskonto weclapp auf der Rechnung ausweist, bestimmt deine weclapp-Steuermatrix gemeinsam mit der Artikelkategorie und dem Versandkostenartikel (default_shipping_article_number). -
Rechnungsausstellung per
DR11verifizieren: Kläre vorab (wie auf Marktplatz-Abrechnung in weclapp beschrieben), ob du selbst an die Endkund:in fakturierst oder ob der Marktplatz-Betreiber die Kundenrechnung alsOPERATORausstellt (dannmirakl_invoice_upload_enabled = false) beziehungsweise ob ein eConsignment-/Streckenkunden-Modell mitcustomer_entity_idundset_purchase_price_as_sales_pricevorliegt. -
Ersten Summenabgleich und ersten MT940-Lauf kontrollieren: Prüfe im Log des Pilotauftrags, dass
reconcile_order_payload_totalsein Delta innerhalb des Cent-Toleranzbands bestätigt und dass die erste erzeugte Rechnung beim späteren MT940-Testimport sauber ausgeziffert wird.
Wichtige Systemgrenzen: Unsere Preis-Umrechnung korrigiert den Importbetrag zwischen Mirakl und weclapp, überschreibt aber niemals fehlerhafte Steuersätze in deinen weclapp-Artikelstammdaten: Ist ein 7-Prozent-Futtermittelartikel in weclapp versehentlich einer 19-Prozent-Kategorie zugeordnet, stimmt zwar der importierte Brutto-Zahlbetrag von 26,75 € auf einem GROSS*-Kanal, weclapp rechnet daraus intern aber 19 statt 7 Prozent Umsatzsteuer heraus. Ebenso loggt reconcile_order_payload_totals Abweichungen bewusst als deutlichen Warnhinweis (ORDER TOTAL MISMATCH), ohne den Versand im Lager hart zu blockieren, und bei Mehrstück-Rundungen im Ein-Cent-Bereich übernimmt deine Buchhaltung gegebenenfalls die Pfennig-Ausbuchung gemäß Kanzleivorgabe. Das ersetzt keine Steuerberatung.
Fazit: Saubere Artikel-Steuerkategorien in weclapp plus Vier-Quadranten-Konvertierung und Summen-Monitoring beim OR11-Import sichern deine Marktplatz-Margen vom ersten Auftrag an ab.
Quellen und Grenzen
Stand: 19. November 2026.
- Mirakl Seller REST API Dokumentation: OR11 (List orders:
order_tax_mode,order_lines[].taxes,shipping_taxes,total_price), DR11 (Accounting document requests) sowie TL03–TL05 (Asynchroner Transaktions-Export) (alle abgerufen am 19.11.2026). - Umsatzsteuerrechtliche Grundlagen: § 4 UStG (Steuerbefreiungen bei Ausfuhr und innergemeinschaftlichen Lieferungen), § 10 UStG (Bemessungsgrundlage), § 12 UStG mit Anlage 2 UStG (Steuersätze 19 % und 7 %) sowie § 13b UStG (Steuerschuldnerschaft des Leistungsempfängers) (alle abgerufen am 19.11.2026).
- weclapp Dokumentation & API: weclapp OpenAPI v2 (
salesOrder,orderItems,shippingCostItems,manualUnitPrice) sowie weclapp-Hilfe: Wie werden Kontoauszüge erkannt? (Referenznummer ab 6 Zeichen & exakter Betragsabgleich) (beide abgerufen am 19.11.2026).
Grenzen dieses Artikels: Dieser Beitrag dokumentiert die technische Preis-, Versandsteuer- und Summenlogik unserer Mirakl-Integration (Mirakl 4 weclapp) gegenüber weclapp und ersetzt keine Steuerberatung zur umsatzsteuerlichen Bewertung deiner Lieferketten, Mischwarenkörbe, Ausfuhrnachweise oder Plattform-Abrechnungsmodelle. Welchen order_tax_mode und welche Steuerfelder ein konkreter Marktplatz übermittelt, legt der jeweilige Plattformbetreiber fest und kann sich durch API-Updates ändern; sämtliche Euro-Beträge im Text sind fiktive Rechenbeispiele. wals.pro steht in keiner gesellschaftsrechtlichen Verbindung zu Mirakl oder den beispielhaft genannten Marktplatz-Betreibern. Das ersetzt keine Steuerberatung.
Weiterlesen: Den vollständigen Architektur-Überblick erhältst du auf Mirakl-Marktplätze an weclapp anbinden und in der Gesamtauswahl Marktplätze an weclapp anbinden. Konkrete Plattform-Beispiele für TAX_EXCLUDED und TAX_INCLUDED zeigen Fressnapf an weclapp anbinden, hygi.de B2B-Marktplatz an weclapp anbinden und zooplus an weclapp anbinden; den nachgelagerten Finanzprozess vertiefen Marktplatz-Abrechnung in weclapp und MT940-Kontoauszug anreichern für automatischen OP-Ausgleich.
Häufige Fragen
Woher weiß ich, ob ein Mirakl-Marktplatz Preise netto (TAX_EXCLUDED) oder brutto (TAX_INCLUDED) an weclapp liefert?
Die verbindliche Auskunft steht direkt im JSON-Auftragsobjekt des Mirakl-Endpunkts OR11 im Feld order_tax_mode sowie in den Positionsfeldern taxes und shipping_taxes. Während Endkunden-Marktplätze wie Shop Apotheke, zooplus oder MediaMarktSaturn regelmäßig TAX_INCLUDED verwenden, liefern B2B-Marktplätze wie hygi.de oder bestimmte Einzelhandels-Setups wie Fressnapf den Wert TAX_EXCLUDED; beim Onboarding prüfen wir deshalb immer einen echten Auftragspayload gegen deinen geplanten weclapp-Vertriebsweg.
Was passiert, wenn TAX_EXCLUDED ungeprüft auf einen GROSS-Vertriebsweg oder einen NET-Vertriebsweg in weclapp trifft?
Trifft ein echter Netto-Einzelpreis aus TAX_EXCLUDED ohne Umrechnung auf einen Brutto-Vertriebsweg (GROSS) in weclapp, behandelt weclapp den Nettopreis fälschlich als Endkunden-Bruttopreis, sodass auf der Rechnung bei 19 Prozent Regelsteuersatz der gesamte Steueraufschlag fehlt. Trifft TAX_EXCLUDED auf einen Netto-Vertriebsweg (NET), stimmen die Artikelpreise zwar bereits überein, aber ältere Skripte ohne Vier-Quadranten-Prüfung ziehen häufig versehentlich die Versandsteuer ein zweites Mal vom bereits netto gelieferten Versandpreis ab. Das ersetzt keine Steuerberatung.
Warum darf ein leeres taxes-Array in Mirakl nicht einfach mit 1,19 multipliziert oder als 0 Prozent gewertet werden?
Manche Mirakl-Plattformen deklarieren im Auftragskopf zwar TAX_EXCLUDED, liefern aber ein leeres taxes-Array aus und übergeben im Feld price_unit bereits den vollen Bruttobetrag, den die Käufer:in gezahlt hat; ein blinder Aufschlag von 19 Prozent würde jede Rechnung überhöhen. Umgekehrt muss ein ausdrücklich gemeldeter Steuersatz von 0,0 Prozent bei Reverse-Charge-Lieferungen oder Drittlands-Ausfuhren strikt respektiert werden, weshalb unsere Logik zwischen fehlenden Steuerdaten (CONVERSION_SKIP_NO_TAX_DATA) und echtem Nullsteuersatz (CONVERSION_SKIP_ZERO_RATE) unterscheidet. Das ersetzt keine Steuerberatung.
Wie rechnet die Schnittstelle gemischte Warenkörbe mit 7 % und 19 % Umsatzsteuer sowie Versandkosten um?
Die Vier-Quadranten-Logik wertet den Steuersatz nicht pauschal für den gesamten Auftrag aus, sondern liest den Satz für jede Bestellposition einzeln aus ihrem jeweiligen taxes-Array und rechnet 7-Prozent- und 19-Prozent-Positionen getrennt in das Zielformat deines weclapp-Vertriebswegs um. Für die Versandkosten summiert die Integration die tatsächlich in shipping_taxes gemeldeten Steuerbeträge über alle Zeilen auf und schlägt sie je nach Quadrant exakt auf den Versandpreis auf oder zieht sie ab; die korrekten Steuersätze in weclapp steuert ergänzend deine weclapp-Steuermatrix. Das ersetzt keine Steuerberatung.
Wie verhindert die Anbindung, dass gerundete Mehrstück-Preise oder Versandkosten zu falschen Summen führen?
Vor dem Speichern jedes Verkaufsauftrags vergleicht reconcile_order_payload_totals den auf Mirakl gezahlten Bruttobetrag unabhängig mit dem Bruttowert des erzeugten weclapp-Payloads und berücksichtigt dabei, dass Mirakl die Versandkosten bereits innerhalb der Positions-Gesamtsummen (total_price) ausweist. Ein enges Rundungs-Toleranzband fängt unvermeidbare Ein-Cent-Abweichungen bei mehrstückigen Positionen auf, während jede echte Betragsabweichung sofort eine sichtbare Meldung im Monitoring auslöst.
Warum hängt der automatische MT940-OP-Ausgleich in weclapp direkt von dieser Steuerlogik ab?
Die automatische Kontoauszugserkennung in weclapp schließt eine offene Ausgangsrechnung beim Einlesen unserer vorangereicherten MT940-Auszahlungsdatei nur dann selbstständig, wenn sowohl die mindestens sechsstellige Rechnungsnummer im Verwendungszweck als auch der Brutto-Rechnungsbetrag mit der Mirakl-Transaktionssumme übereinstimmen. Verfälscht ein falscher Steuer-Quadrant oder eine doppelt abgezogene Versandsteuer den Rechnungsbetrag in weclapp, stimmen Rechnung und Auszahlungsbuchung nicht mehr überein und jeder Posten muss manuell nachbearbeitet werden. Das ersetzt keine Steuerberatung.