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 sowie ein Wert in der jeweiligen Zeile vorhanden ist.

Bei produktbezogenen Feldern gilt:
Der Wert wird ausschließlich aus der ersten Zeile eines Produkts übernommen. Nachfolgende Zeilen desselben Produkts (z. B. weitere SKUs/Varianten) können zwar Werte enthalten, diese werden jedoch ignoriert.

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

Wichtig

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
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 den Farbfilter. Wird als Fallback für productOriginalColor verwendet, wenn dieses Feld nicht angegeben ist.	blau (denn navy=blau) oder blau::grün::gelb (doppelter Doppelpunkt für mehrere Farben, die separat im Filter erscheinen)
productOriginalColor	alphanumerisch	Originaler Farbwert des Produkts (Ausgabe an der Farbauswahl). Wird dieses Feld nicht angegeben, leitet ConversionBuddy den Wert automatisch aus productColor ab – bei mehreren Farben werden diese mit / verbunden (z.B. blau/grün).	navy
productColorGroupId	alphanumerisch (keine Sonderzeichen außer _ - . , ~)	Farbübergreifende Master-Id eines Produktes. Erfordert mindestens die Angabe von productColor und optional auch productOriginalColor. Produkte derselben Gruppe werden als Related Products (Farbauswahl) zusammengefasst. Das Thumbnail je Farbe richtet sich nach der Thumbnail-Logik für Related Products.	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
colorImageUrl	URL (https)	Farbspezifisches Produktbild für die Thumbnail-Anzeige in der Related-Products-Farbauswahl. Das Verhalten bei teilweiser Befüllung innerhalb einer colorGroup hängt vom Flag colorImageMixAllowed ab – siehe Thumbnail-Logik für Related Products.	https://cdn.shop.io/img/products/shirt-navy.png
colorSwatchUrl	URL (https)	Farb-Swatch (Farbkreis als SVG/Bild) zur Anzeige in der Produktliste. Wird, sofern gesetzt, pro Produkt direkt verwendet und hat Vorrang vor dem farbbasierten Swatch aus den Template-Assets (colorSwatches, gemappt über productColor); ohne Wert greift der Fallback auf das Produktbild.	https://cdn.shop.io/img/swatches/black.svg
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

Thumbnail-Logik für Related Products (colorImageUrl)

Wird productColorGroupId genutzt, um Produkte als Related Products (Farbauswahl) zusammenzufassen, bestimmt die folgende Logik, welches Bild je Farbe als Thumbnail verwendet wird. Die Entscheidung wird pro colorGroup getroffen.

Situation	Thumbnail	Feed-Warning
Alle Produkte der Gruppe haben colorImageUrl	colorImageUrl	—
Kein Produkt der Gruppe hat colorImageUrl	erstes productImageUrl	—
Mix: nur ein Teil der Gruppe hat colorImageUrl, Flag colorImageMixAllowed = false (Standard)	erstes productImageUrl für alle Produkte der Gruppe	Ja – sichtbar im Feed-Report
Mix: nur ein Teil der Gruppe hat colorImageUrl, Flag colorImageMixAllowed = true	colorImageUrl wo vorhanden, sonst erstes productImageUrl	—

Store-Flag colorImageMixAllowed

Das Flag colorImageMixAllowed steuert das Verhalten bei inkonsistenter colorImageUrl-Abdeckung innerhalb einer colorGroup (Mix-Fall):

• false (Standard): Strikte Konsistenz – bei einem Mix fällt die gesamte Gruppe auf productImageUrl zurück. Im Feed-Report wird eine Warning mit der betroffenen productColorGroupId ausgegeben, damit Feed-Verantwortliche den Fehler erkennen und beheben können.
• true: Permissiver Mix – colorImageUrl wird genutzt wo vorhanden, fehlende Werte werden mit productImageUrl aufgefüllt. Keine Warning.

Hinweis

Das Flag colorImageMixAllowed ist eine serverseitige Store-Konfiguration und kein Feed-Feld. Es wird durch das ConversionBuddy-Team konfiguriert.

Optionale Varianten-Felder

Feldname	Typ	Beschreibung	Beispiel
addToCartUrl	URL (https)	Ziel-URL, mit der die SKU per GET direkt in den Warenkorb des Zielshops gelegt werden kann	https://shop.io/cart/add?sku=sku1
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
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 und überschreibt den Standard („ab“ wird sonst nur angezeigt, wenn Variantenpreise unterschiedlich sind).	ab
priceInformation	alphanumerisch	Preis-Information, die im Layer unter dem Preis angezeigt wird	inkl. Basic-Gläser
availabilityCount	Ganzzahl	Verfügbare Menge	1
certification	Kombination (getrennt durch :)	EPREL-Zertifizierung des Produkts (Energieeffizienz) im Format EC:EPREL:code	EC:EPREL:123456
size	alphanumerisch	Größe	XL
imageUrl[0-9]	URL (https)	Bild-URL (max. 800px) der Variante; wird, wenn vorhanden, vor den Produktbildern ausgegeben	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.

Fulfillment-Typ

Mit dem Fulfillment-Typ lässt sich steuern, ob eine Variante eine versendbare Ware oder eine nicht-versendbare Leistung (z.B. ein Änderungsservice für Kleidung) ist. Dies ist unabhängig von den Versandkosten und erlaubt es, für reine Dienstleistungen keine Versandinformationen auszuspielen.

Feldname	Typ	Beschreibung	Beispiel
fulfillmentType	Festwert (shippable, service)	Fulfillment-Typ der Variante. shippable = versendbare Ware, service = Leistung/nicht versendbar. Standardwert = shippable.	service

Die Werte werden unabhängig von der Groß-/Kleinschreibung eingelesen. Fehlt das Feld, ist es leer oder enthält einen unbekannten Wert, gilt der Standardwert shippable.

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.