Data Feed

The ConversionBuddy data feed consists of a text file in CSV format. The feed is provided via HTTPS (URL) for further processing by ConversionBuddy. The feed consists of a set of mandatory fields as well as optional additional fields that can be defined freely.

Structure and Syntax

The data feed is created in CSV format. To ensure error-free processing by ConversionBuddy, the following requirements must be met:

• Provided via https
• Encoding: UTF-8
• Delimiter: , (recommended; alternatively ; or | are also possible)
• Field values are enclosed in quotation marks ""
• The order of the columns is not relevant. Recommended order: mandatory fields first, then custom fields.
• Fields based on numeric values can be specified as integers (e.g. 5) or as floating-point values (5.0). Floating-point values must use a dot as the decimal separator.

Mandatory Fields

The following fields (columns) must exist in the feed. Otherwise, error-free processing is not possible.

Note

Mandatory field means that a column with the corresponding name exists and that a value is present in the respective row.

For product-related fields:
The value is taken exclusively from the first row of a product. Subsequent rows of the same product (e.g. additional SKUs/variants) may contain values, but these are ignored.

Product Mandatory Fields

Field name	Type	Description	Example
productId	alphanumeric (no special characters except _ - . , ~)	Product ID	1
title	alphanumeric	Title/name of the product	Checked shirt
categoryPath	alphanumeric	Category path with delimiter: > (no spaces)	Men>Shirts
productImageUrl[0-9]	URL (https)	Product image URL (max. 800px)	https://shop.io/img/1.jpg

Variant Mandatory Fields

Important

The field productId must be present in every row of the data feed. If a row contains a variant, this field sets the product to be referenced (in this case, for example, all variants of a product have the same value for productId). Likewise, the field sku is mandatory in every row – even if there is only one variant. In this case, sku can have the same value as productId.

Field name	Type	Description	Example
sku	alphanumeric (no special characters except _ - . , ~)	Variant ID	1-1
availability	fixed value (backorder, discontinued, in_stock, limited_availability, out_of_stock, preorder, presale, sold_out)	Availability of the variant. Default value = in_stock. During the transition period, availabilityCount is used as a fallback for availability!	in_stock
price	floating point	Sales price	99.90
productUrl	URL (https)	Deeplink	https://shop.io/1

Optional Fields

The optional fields do not necessarily have to exist in the feed, but they are part of the standard.

Optional Product Fields

Field name	Type	Description	Example
productBulletPoints	alphanumeric (multi-value compatible)	List of values displayed as bullet points (e.g. USPs) in the product layer, replacing the shortDescription.	Sustainable materials::Handcrafted product::High wearing comfort (double colon separates the individual bullet points)
productColor	alphanumeric (multi-value compatible)	Normalized color(s) of the product. Basis for the color filter. Used as a fallback for productOriginalColor if that field is not specified.	blue (since navy=blue) or blue::green::yellow (double colon for multiple colors, which appear separately in the filter)
productOriginalColor	alphanumeric	Original color value of the product (displayed in the color selection). If this field is not specified, ConversionBuddy automatically derives the value from productColor – multiple colors are joined with / (e.g. blue/green).	navy
productColorGroupId	alphanumeric (no special characters except _ - . , ~)	Cross-color master ID of a product. Requires at least productColor and optionally productOriginalColor. Products of the same group are grouped as related products (color selection). The thumbnail per color follows the thumbnail logic for related products.	1234-5
productMaterial	alphanumeric	Product material	Linen
brand	alphanumeric	Brand	Walbusch
brandImageUrl	URL (https)	URL of the brand logo, if a brand is specified	https://cdn.shop.io/img/brands/brand.png
colorImageUrl	URL (https)	Color-specific product image for the thumbnail display in the related-products color selection. The behavior with partial coverage within a colorGroup depends on the colorImageMixAllowed flag – see thumbnail logic for related products.	https://cdn.shop.io/img/products/shirt-navy.png
colorSwatchUrl	URL (https)	Color swatch (color circle as SVG/image) for display in the product list. If set, it is used directly per product and takes precedence over the color-based swatch from the template assets (colorSwatches, mapped via productColor); without a value, the fallback to the product image applies.	https://cdn.shop.io/img/swatches/black.svg
gender	fixed value (male, female or unisex)	Gender – can be used for filtering within the product list.	unisex
childGender	fixed value (boy, girl or unisex)	Gender of a child – can be used for filtering within the product list.	unisex
uniqueCharacteristic1	alphanumeric	Reference to a variant field (field name) that leads to a selection.	size
uniqueCharacteristic2	alphanumeric	Reference to a variant field (field name) that leads to a second selection.	collar
uniqueCharacteristic3	alphanumeric	Reference to a variant field (field name) that leads to a third selection.	height
uniqueCharacteristic4	alphanumeric	Reference to a variant field (field name) that leads to a fourth selection.	width
rating	floating point (max=5.0)	Product rating	3.5
ratingCount	integer or empty/null	Total number of ratings. A null value means the rating count is not displayed.	200
shortDescription	string	Short description with max. 80 characters. A line break can be forced with <br> (max. once). Anything longer than 80 characters is truncated with "..." (tooltip shows the full shortdescription).	with shark collar
tags	One or more tags (alphanumeric). Delimiter for multiple tags is ~ (OR) or + (AND).	Products with tags can be accessed via the landing page with URI /t/[tag] or /t/[tag1]~[tag2] or /t/[tag1]+[tag2].	tag1 or tag1::tag2
productGoogleCat	alphanumeric	Google Shopping category (as ID or category tree)	2271 or Apparel & Accessories > Clothing > Dresses

Thumbnail Logic for Related Products (colorImageUrl)

If productColorGroupId is used to group products as related products (color selection), the following logic determines which image is used as the thumbnail per color. The decision is made per colorGroup.

Situation	Thumbnail	Feed warning
All products of the group have colorImageUrl	colorImageUrl	—
No product of the group has colorImageUrl	first productImageUrl	—
Mix: only part of the group has colorImageUrl, flag colorImageMixAllowed = false (default)	first productImageUrl for all products of the group	Yes – visible in feed report
Mix: only part of the group has colorImageUrl, flag colorImageMixAllowed = true	colorImageUrl where available, otherwise first productImageUrl	—

Store Flag colorImageMixAllowed

The colorImageMixAllowed flag controls the behavior in case of inconsistent colorImageUrl coverage within a colorGroup (mix case):

• false (default): Strict consistency – in case of a mix, the entire group falls back to productImageUrl. A warning with the affected productColorGroupId is issued in the feed report so that feed managers can identify and fix the issue.
• true: Permissive mix – colorImageUrl is used where available; missing values are filled with productImageUrl. No warning.

Note

The colorImageMixAllowed flag is a server-side store configuration and not a feed field. It is configured by the ConversionBuddy team.

Optional Variant Fields

Field name	Type	Description	Example
addToCartUrl	URL (https)	Target URL that can be used to add the SKU directly to the target shop's cart via GET	https://shop.io/cart/add?sku=sku1
availabilityDate	date (YYYY-MM-DD or YYYY-MM-DDThh:mm)	Availability date of the variant in ISO 8601 UTC format. Mandatory when using an availability with the value preorder or backorder.	2025-12-31
lowestPrice	floating point	Lowest price of the last 30 days	119.90
oldPrice	floating point	Strikethrough price (> price)	119.90
pricePrefix	alphanumeric	Price prefix. If set, the prefix is always displayed before the price in product lists and overrides the default ("from" is otherwise only displayed if variant prices differ).	from
priceInformation	alphanumeric	Price information displayed in the layer below the price	incl. basic lenses
availabilityCount	integer	Available quantity	1
certification	combination (separated by :)	EPREL certification of the product (energy efficiency) in the format EC:EPREL:code	EC:EPREL:123456
size	alphanumeric	Size	XL
imageUrl[0-9]	URL (https)	Image URL (max. 800px) of the variant; if present, displayed before the product images	https://shop.io/img/1.jpg

Shipping Costs

Delivery/shipping costs can be defined separately for each variant. This allows, for example, badges like "free shipping" to be displayed in the frontend:

Field name	Type	Description	Example
shipping	floating point	Shipping costs	4.99 (or 0.0 for free shipping)

If the shipping field is not filled or not present in the feed, shipping costs are ignored. Only shipping costs >= 0.0 are taken into account.

Fulfillment Type

The fulfillment type controls whether a variant is a shippable good or a non-shippable service (e.g. a clothing alteration service). This is independent of the shipping costs and makes it possible to not display any shipping information for pure services.

Field name	Type	Description	Example
fulfillmentType	fixed value (shippable, service)	Fulfillment type of the variant. shippable = shippable good, service = service/not shippable. Default value = shippable.	service

The values are read case-insensitively. If the field is missing, empty, or contains an unknown value, the default value shippable applies.

Base Prices

The German Price Indication Ordinance (Preisangabenverordnung) requires that in trade with end consumers, not only the final price but also the converted price per unit of measurement (base price) must be indicated in the immediate vicinity of the final price when goods are offered by weight, volume, length, or area. Base prices can be transmitted in the feed with two additional fields:

Field name	Type	Description	Example
basePrice	floating point	Base price	4.99
basePriceUnit	base price unit	Unit of measurement	100ml
oldBasePrice	floating point	Strikethrough base price – requires the presence of oldPrice, basePrice, and basePriceUnit	5.99

Dynamic Pricing and Vouchers

With dynamic pricing, the price of a variant can be overridden per channel. Alternatively or in combination with the price, a voucher code can be specified, which opens in a layer. The placeholder [PROMO_KEY] reflects an abbreviation for the corresponding channel or promotion. The abbreviation should be short & meaningful and must not contain special characters, e.g. wsv2026. So that price, voucher, and text can be combined into one promotion during feed processing, all related fields of a promotion must be given the same value for [PROMO_KEY]: promoPrice_wsv2026, promoText_wsv2026, promoVoucher_wsv2026. All fields are optional. It is possible to set only the price, only the voucher code with text, or all three fields.

Field name	Type	Description	Example
promoPrice_[PROMO_KEY]	floating point	Different price of the SKU for this promotion, if this field exists and is filled.	1.99
promoText_[PROMO_KEY]	alphanumeric (<br> allowed) or empty/null	Promo text displayed in the voucher layer. Text before is displayed as the "headline" in the voucher layer. Text after is displayed in smaller font size in additional lines. Only one is possible.	Save 10% now!
promoVoucher_[PROMO_KEY]	alphanumeric	Voucher code to be promoted with this promotion. If this field is set, a corresponding badge is displayed in the product list and on the product itself. Clicking on the product then leads to the intermediate voucher overlay (where the code can be copied to the clipboard).	SSV10

Activation via URL Parameter

The URL parameter cb.pmo=[PROMO_KEY] activates the respective promotion.

Default Promotion

It is possible to define a default promotion in the feed that is active immediately (**without setting the parameter ** cb.pmo). If a default promotion is defined in the feed, it becomes active according to the following rules:

• The parameter cb.pmo is not present or empty (default promotion is active)
• The parameter cb.pmo exists, but no promotion with that value is configured in the feed (default promotion is active)
• The parameter cb.pmo exists and a promotion from the feed can be matched (promotion is active, default promotion is not active)

Important

A promotion matching the parameter cb.pmo always takes precedence over a default promotion.

A default promotion can be created with the PROMO_KEY default (e.g. promoType_default). Within a product, regular promotions can be combined with a default promotion.

Custom Fields

In addition to the mandatory fields, custom fields can be added to the feed. These are useful when, for example, individual customer requirements are to be implemented. Custom fields can be used both as product properties and as variant properties. Field names must be written in camelCase, with the first word starting with a lowercase letter.

Example of a product-related custom field: productManufacturer.

Custom Product Fields

To extend the respective product with new properties, the field must begin with the prefix product. It is important to note that a product field should not be a property that is a distinguishing feature of a variant (SKU), such as size.

Examples of custom product fields:

• productManufacturer
• productCountryOfOrigin

Note

The values are multi-value compatible (delimiter ::). Example: EU::Europe

Custom Variant Fields

Variant fields can be used to add additional properties to the respective product variant. In contrast to custom product fields, these do not need to be given a prefix.

Examples of custom variant fields:

• height
• width

Error Tolerance

There is a general error tolerance. The feed is always imported and published without the faulty products. Products with a faulty variant are also completely discarded. The status in the feed report and in the corresponding email notifications is determined by the number of invalid rows relative to the total number (error rate):

• SUCCESS: no errors, all products imported; an email is sent if the previous status was WARN or ERROR
• WARN: error rate <= 0.5%, only fully valid products were imported, no email is sent
• ERROR: error rate > 0.5%, only fully valid products were imported, an email is sent

Note

With a 100% error rate (every row faulty), an empty feed is still published, which means that all products are redirected to the target shop (fallback)

Feed Publication

The data feed must be provided via URL (HTTPS) for processing by ConversionBuddy.

Automatic Detection of Feed Changes

The ConversionBuddy feed loader automatically detects changed feed data based on the ETag HTTP header or alternatively the Last-Modified header. It must therefore always be verified that the ETag and/or Last-Modified headers are included in the HTTP response when retrieving the CSV.

Hosting providers such as AWS automatically add the necessary ETag in the S3 service when storing files. An individual implementation is not necessary. If, for example, Apache2 is used as the web server, the ETag header can be configured individually.

See Apache2 documentation.

The feed loader checks every 5 minutes via HTTP HEAD for a new feed version. If the ETag or Last-Modified headers have not changed since the last successful import, no new import process is triggered.

Important

If both the ETag header and the Last-Modified header are missing, the data feed is always re-read every 5 minutes, which leads to large data volumes and high server load.

Retention Period

After the current feed has been read, it is published automatically and without delay. In addition, the last version is stored as a backup in ConversionBuddy.