Datenfeed

Der ConversionBuddy Datenfeed besteht aus einer Textdatei im CSV-Format. Der Feed wird per HTTPS (URL) für die weitere Verarbeitung durch ConversionBuddy bereitgestellt. Der Feed besteht aus einer Reihe von Pflichtfeldern sowie optionalen Zusatzfeldern, die frei definiert werden können.

Aufbau und Syntax

Der Datenfeed wird im CSV-Format erstellt. Damit eine fehlerfreie Verarbeitung durch ConversionBuddy gewährleistet ist, müssen folgende Anforderungen eingehalten werden:

• Bereitstellung per https
• Encoding: UTF-8
• Trennzeichen: , (empfohlen, alternativ sind auch ; oder | möglich)
• Feld-Werte werden mit Anführungszeichen "" umschlossen
• Die Reihenfolge der Spalten ist nicht relevant. Empfohlene Reihenfolge: Erst die Pflichtfelder, dann die Individualfelder.
• Felder, die auf numerischen Werten basieren, können als Ganzzahl (z.B. 5) oder als Fließkommawerte angegeben werden (5.0). Fließkommawerte müssen mit Punkt als Dezimaltrennzeichen angegeben werden.

Pflichtfelder

Die folgenden Felder (Spalten) müssen im Feed existieren. Ansonsten ist eine fehlerfreie Verarbeitung nicht möglich.

Hinweis

Pflichtfeld bedeutet, dass eine Spalte mit dem entsprechenden Namen vorhanden ist und nicht, dass auch zwingend ein Wert vergeben sein muss. Alle Feldnamen sind case-sensitive (Groß-/Kleinschreibung ist relevant).

Produkt Pflichtfelder

Feldname	Typ	Beschreibung	Beispiel
productId	alphanumerisch (keine Sonderzeichen außer _ - . , ~)	Produkt-ID	1
title	alphanumerisch	Titel/Name des Produkts	Kariertes Hemd
categoryPath	alphanumerisch	Kategorie-Pfad mit Trennzeichen: > (keine Leerzeichen)	Herren>Hemden
productImageUrl[0-9]	URL (https)	Produktbild-URL (max. 800px)	https://shop.io/img/1.jpg

Varianten Pflichtfelder

Das Feld productId muss zwingend in jeder Zeile des Datenfeeds vorhanden sein. Handelt es sich um eine Zeile mit einer Variante, so wird über das dieses Feld das zu referenzierende Produkt gesetzt (in diesem Fall haben beispielsweise alle Varianten eines Produkts denselben Wert für productId). Ebenso ist das Feld sku in jeder Zeile Pflicht – auch wenn es nur eine Variante gibt. In diesem Fall kann sku denselben Wert wie productId haben.

Feldname	Typ	Beschreibung	Beispiel
sku	alphanumerisch (keine Sonderzeichen außer _ - . , ~)	Varianten-ID	1-1
availability	Festwert (backorder, discontinued, in_stock, limited_availability, out_of_stock, preorder, presale, sold_out)	Verfügbarkeit der Variante. Standardwert = in_stock. Im Übergangszeitraum wird als Fallback availabilityCount für die Verfügbarkeit herangezogen!	in_stock
availabilityDate	Datum (YYYY-MM-DD oder YYYY-MM-DDThh:mm)	Verfügbarkeitsdatum der Variante im ISO 8601 UTC Format. Pflichtangabe bei Nutzung einer availability mit dem Wert preorder oder backorder.	2025-12-31
price	Fließkomma	Verkaufspreis	99.90
productUrl	URL (https)	Deeplink	https://shop.io/1

Optionale Felder

Die optionalen Felder müssen nicht zwingend im Feed existieren, sind aber Bestandteil des Standards.

Optionale Produkt-Felder

Feldname	Typ	Beschreibung	Beispiel
productBulletPoints	alphanumerisch (multiwert-kompatibel)	Liste von Werten, die im Product-Layer als Bullet-Points (z.B. USPs) ausgeben wird und die shortDescription ersetzt.	Nachhaltige Materialien::Handgefertigtes Produkt::Hoher Tragekomfort (Doppelter Doppelpunkt trennt die einzelnen Bullet-Points)
productColor	alphanumerisch (multiwert-kompatibel)	normalisierte Farbe(n) des Produkts (Basis für Filter und Ausgabe an der Farbauswahl, falls keine productOriginalColor angegeben ist)	blau (denn navy=blau) oder blau::grün::gelb (Doppelter Doppelpunkt für mehrere Farben, die separat im Filter erscheinen)
productOriginalColor	alphanumerisch	original Farbwert des Produkts (Ausgabe an der Farbauswahl)	navy
productColorGroupId	alphanumerisch (keine Sonderzeichen außer _ - . , ~)	Farbübergreifende Master-Id eines Produktes. Erfordert mindestes die Angabe von "productColor" und optional auch "productOriginalColor".	1234-5
productMaterial	alphanumerisch	Produktmaterial	Leinen
brand	alphanumerisch	Marke	Walbusch
brandImageUrl	URL (https)	URL des Markenlogos, wenn eine Marke angegeben ist	https://cdn.shop.io/img/brands/brand.png
gender	Festwert (male, female oder unisex)	Geschlecht - nutzbar für eine Filterung innerhalb der Produkt-Liste.	unisex
childGender	Festwert (boy, girl oder unisex)	Geschlecht eines Kindes - nutzbar für eine Filterung innerhalb der Produkt-Liste.	unisex
uniqueCharacteristic1	alphanumerisch	Referenz auf Variantenfeld (Feldname), die zu einer Auswahl führt.	size
uniqueCharacteristic2	alphanumerisch	Referenz auf Variantenfeld (Feldname), die zu einer zweiten Auswahl führt.	collar
uniqueCharacteristic3	alphanumerisch	Referenz auf Variantenfeld (Feldname), die zu einer dritten Auswahl führt.	height
uniqueCharacteristic4	alphanumerisch	Referenz auf Variantenfeld (Feldname), die zu einer vierten Auswahl führt.	width
rating	Fließkomma (Max=5.0)	Produkt-Bewertung	3.5
ratingCount	Ganzzahl oder leer/null	Anzahl Bewertungen gesamt. Ein Null-Wert führt dazu, dass die Bewertungs-Anzahl nicht ausgegeben wird.	200
shortDescription	string	Kurzbeschreibung mit max. 80 Zeichen. Zeilenumbruch kann mit <br> erzwungen werden (max. einmal). Alles größer 80 Zeichen wird mit "..." abgeschnitten (Tooltip zeigt vollständige shortdescription).	mit Haifischkragen
tags	Ein oder mehrere Tags (alphanumerisch). Trennzeichen für mehrere Tags ist ~ (ODER) oder + (UND).	Mit Tags versehene Produkte können über die Landingpage mit URI /t/[tag] oder /t/[tag1]~[tag2] bzw. /t/[tag1]+[tag2] aufgerufen werden.	tag1 oder tag1::tag2
productGoogleCat	alphanumerisch	Google Shopping Kategorie (als ID oder Kategoriebaum)	2271 oder Bekleidung & Accessoires > Bekleidung > Kleider

Optionale Varianten-Felder

Feldname	Typ	Beschreibung	Beispiel
addToCartUrl	URL (https)	Ziel-URL, mit der die SKU perGET direkt in den WK des Zielshops gelegt werden kann	https://shop.io/cart/add?sku=sku1
lowestPrice	Fließkomma	Niedrigster Preis der letzten 30 Tage	119.90
oldPrice	Fließkomma	Streichpreis ( > price)	119.90
pricePrefix	alphanumerisch	Preis-Präfix, wenn gesetzt, wird das Präfix immer in Produktlisten vor dem Preis ausgegeben - hiermit wird der Standard überschrieben (ab wird nur ausgegeben, wenn unterschiedliche Variantenpreise existieren	ab
priceInformation	alphanumerisch	Preis-Information, die im Layer unter dem Preis angezeigt wire.	inkl. Basic-Gläser
availabilityCount	Ganzzahl	Verfügbare Menge	1
certification	Kombination (getrennt durch :)	EPREL-Zertifizierung des Produkts (Energieeffizienz) i Format EC:EPREL:code	EC:EPREL:123456
size	alphanumerisch	Größe	XL
imageUrl[0-9]	URL (https)	Bild-URL (max. 800px) der Variante (wenn vorhanden Ausgabe vor den Produktbildern)	https://shop.io/img/1.jpg

Versandkosten

Liefer-/Versandkosten können für jede Variante separat definiert werden. Hiermit können z.B. Störer wie "Gratisversand" im Frontend ausgespielt werden:

Feldname	Typ	Beschreibung	Beispiel
shipping	Fließkomma	Versandkosten	4.99 (oder auch 0.0 für kostenlosen Versand)

Wenn das Feld shipping nicht befüllt oder nicht im Feed vorhanden ist, werden die Versandkosten ignoriert. Es werden ausschließlich Versandkosten >= 0.0 berücksichtigt.

Grundpreise

Die Preisangabenverordnung verlangt, dass im Handel mit Endverbrauchern nicht nur der Endpreis, sondern auch der umgerechnete Preis je Mengeneinheit (Grundpreis) in unmittelbarer Nähe des Endpreises anzugeben ist, wenn Waren nach Gewicht, Volumen, Länge oder Fläche angeboten werden. Grundpreise können mit zwei weiteren Feldern im Feed übermittelt werden:

Feldname	Typ	Beschreibung	Beispiel
basePrice	Fließkomma	Grundpreis	4.99
basePriceUnit	Grundpreis-Einheit	Mengeneinheit	100ml
oldBasePrice	Fließkomma	Streich-Grundpreis - setzt das Vorhandensein von oldPrice, basePrice sowie basePriceUnit voraus	5.99

Dynamic Pricing und Gutscheine

Mit Dynamic Pricing kann der Preis einer Variante kanal-spezifisch überschrieben werden. Alternativ oder in Kombination mit dem Preis kann ein Gutschein-Code angegeben werden, der sich in einem Layer öffnet. Der Platzhalter [PROMO_KEY] spiegelt ein Kürzel für den entsprechenden Kanal bzw. die Promotion wider. Das Kürzel sollte knapp & aussagekräftig sein und darf keine Sonderzeichen enthalten, z.B. wsv2026. Damit Preis, Gutschein und Text bei der Feed-Verarbeitung zu einer Promotion zusammengefasst werden können, müssen alle zusammengehörenden Felder einer Promotion mit demselben Wert für [PROMO_KEY] versehen werden: promoPrice_wsv2026, promoText_wsv2026, promoVoucher_wsv2026. Alle Felder sind optional. Es ist möglich, nur den Preis zu setzen, nur den Gutschein-Code mit Text oder auch alle drei Felder.

Feldname	Typ	Beschreibung	Beispiel
promoPrice_[PROMO_KEY]	Fließkomma	Abweichender Preis der SKU für diese Promotion, wenn dieses Feld existiert und gefüllt ist.	1.99
promoText_[PROMO_KEY]	alphanumerisch (<br> erlaubt) oder leer/null	Promo-Text, der im Gutschein-Layer angezeigt wird. Text vor wird als "Headline" im Gutschein-Layer dargestellt. Text nach wird in kleinerer Schriftgröße in weiteren Zeilen angezeigt. Es ist nur ein möglich.	Jetzt 10% sparen!
promoVoucher_[PROMO_KEY]	alphanumerisch	Gutschein-Code, der mit dieser Promotion beworben werden soll. Ist dieses Feld gesetzt, so wird ein entsprechender Störer in der Produktliste sowie am Produkt selbst angezeigt. Ein Klick auf das Produkt führt dann zum zwischengeschalteten Gutschein-Overlay (dort kann der Code in die Zwischenablage kopiert werden).	SSV10

Aktivierung via URL-Parameter

Mit dem URL-Parameter cb.pmo=[PROMO_KEY] wird die jeweilige Promotion aktiviert.

Default Promotion

Es ist möglich, eine Default-Promotion im Feed zu definieren, die sofort aktiv ist (**ohne Setzen des Parameters ** cb.pmo). Sofern eine Default-Promotion im Feed definiert ist, wird diese nach den folgenden Regeln aktiv:

• Der Parameter cb.pmo ist nicht vorhanden oder leer (Default-Promotion ist aktiv)
• Der Parameter cb.pmo existiert, jedoch ist kein Promotion mit dem Wert im Feed konfiguriert (Default-Promotion ist aktiv)
• Der Parameter cb.pmo existiert und es kann eine Promotion aus dem Feed zugeordnet werden (Promotion ist aktiv, Default-Promotion ist nicht aktiv)

Wichtig

Eine zum Parameter cb.pmo passende Promotion hat immer Vorrang vor einer Default-Promotion.

Eine Default-Promotion kann mit dem PROMO_KEY default angelegt werden (z.B. promoType_default). Innerhalb eines Produktes können reguläre Promotions mit einer Default-Promotion kombiniert werden.

Individual-Felder

Zusätzlich zu den Pflichtfeldern können individuelle Felder im Feed ergänzt werden. Sinnvoll sind diese, wenn beispielsweise individuelle Kundenanforderungen umgesetzt werden sollen. Individualfelder können sowohl als Produkt-Eigenschaft, als auch als Varianten-Eigenschaft genutzt werden. Feldnamen müssen in CamelCase-Schreibweise benannt werden, wobei der Wortanfang mit einem Kleinbuchstaben beginnt.

Beispiel für ein produktbezogenes Individualfeld: productManufacturer.

Individuelle Produktfelder

Um das jeweilige Produkt um neue Eigenschaften zu erweitern, muss das Feld mit dem Präfix product beginnen. Es ist wichtig zu berücksichtigen, dass ein Produktfeld keine Eigenschaft sein sollte, die ein Unterscheidungsmerkmal einer Variante (SKU) darstellt (Größe).

Beispiele für individuelle Produktfelder:

• productManufacturer
• productCountryOfOrigin

Hinweis

Die Werte sind multiwert-kompatibel (Trennzeichen ::). Beispiel: EU::Europa

Individuelle Variantenfelder

Variantenfelder können genutzt werden, um die jeweilige Produkt-Variante um zusätzliche Eigenschaften zu ergänzen. Im Gegensatz zu den individuellen Produktfeldern, müssen diese nicht mit einem Präfix versehen werden.

Beispiele für individuelle Variantenfelder:

• height
• width

Fehlertoleranz

Es gibt eine allgemeine Fehlertoleranz. Der Feed wird immer ohne die fehlerbehafteten Produkte importiert und veröffentlicht. Auch Produkte mit einer fehlerhaften Variante werden dabei vollständig verworfen. Der Status im Feed-Report und in den entsprechenden E-Mail-Benachrichtungen wird anhand der Anzahl der invaliden Zeilen bezogen auf die Gesamtanzahl (Error-Rate) bestimmt:

• SUCCESS: keine Fehler, alle Produkte importiert, es wird eine E-Mail gesendet, sofern der vorherige Status WARN oder ERROR war
• WARN: Error-Rate <= 0,5%, nur vollständig valide Produkte wurden importiert, es wird keine E-Mail gesendet
• ERROR: Error-Rate > 0,5%, nur vollständig valide Produkte wurden importiert, es wird eine E-Mail gesendet

Hinweis

Bei einer 100% Error-Rate (jede Zeile fehlerhaft) wird trotzdem ein leerer Feed veröffentlicht, was dazu führt, dass für sämtliche Produkte in den Zielshop geleitet wird (Fallback)

Feed-Veröffentlichung

Der Datenfeed muss via URL (HTTPS) zur Verarbeitung durch ConversionBuddy bereitgestellt werden.

Automatische Erkennung von Feed-Änderungen

Der ConversionBuddy Feed-Loader erkennt geänderte Feed-Daten automatisch anhand des ETag HTTP-Headers oder alternativ am Last-Modified-Header. Es muss also in jedem Fall geprüft werden, ob ETag- und/oder Last-Modified-Header bei Abruf des CSV in der HTTP-Response enthalten sind.

Hosting-Anbieter wie AWS ergänzen im S3-Service vollautomatisch das notwendige ETag bei Speicherung. Eine individuelle Implementierung ist nicht notwendig. Wird beispielsweise der Apache2 als Webserver eingesetzt, so kann der ETag-Header individuell konfiguriert werden. Siehe Apache2-Dokumentation.

Der Feed-Loader prüft alle 5 Minuten per Http HEAD auf eine neue Feed-Version. Sollten sich ETag- oder Last-Modified-Header seit dem letzten erfolgreichen Import nicht verändert haben, wird auch kein erneuter Import-Vorgang angestoßen.

Wichtig

Fehlen sowohl ETag-Header als auch Last-Modified-Header, wird der Datenfeed immer alle 5 Minuten neu eingelesen, was zu großen Datenmengen und hoher Server-Last führt.

Aufbewahrungsdauer

Nach Einlesen des aktuellen Feeds, wird dieser automatisiert und ohne zeitliche Verzögerung veröffentlicht. Zusätzlich wird die letze Version als Backup in ConversionBuddy gespeichert.