Legacy Datafeed Specifications

Overview:

The product catalog datafeed drives many of the tools that AvantLink provides to affiliates. The requirements for how the datafeed is supplied are as follows:

  1. The datafeed file must be an ASCII text file in comma-separated (csv), tab-delimited, or pipe-delimited (|) format. Standard to all such delimited text files, the following restrictions apply:
    • Each line in the datafeed file should be separated by a newline character (\n) or a carriage return + newline sequence (\r\n).
    • Each product/record in the datafeed file should be listed on a single line. Carriage return (\r) or newline (\n) characters within fields such as the product description must be stripped out before outputting to the file.
    • The character used to separate fields within the datafeed file must be properly stripped or escaped using field qualifiers. In particular, the following guidelines should be followed:
      • For comma-separated (csv) data: use quotes (") around text fields that may include commas. Then escape quotes within each field by doubling them (i.e. "This field has a "quoted" word" would become "This field has a ""quoted"" word").
      • For tab-delimited data: strip tabs from any fields and replace them with single spaces.
      • For pipe-delimited data: strip pipes (|) from any fields and replace them with single spaces or an alternate character of your choosing.
    • Spreadsheet programs such as OpenOffice.org Calc or Microsoft Excel are useful in validating delimited-text files. If the datafeed file opens without any warnings in a spreadsheet, and the data is properly lined up in columns, then the file is likely well formatted.
  2. The first line of the datafeed file should contain the field names used in the file, to provide a reference for the layout of the information.
  3. The datafeed file must include at least the following information (see Datafeed Fields below for an explanation of each field):
    • SKU
    • Product Name
    • Long Description
    • Category
    • Image URL
    • Buy Link (Merchant product detail page url)
    • Retail Price

    The more detail that is available in the datafeed the better. The above list is only the minimum required information.

  4. Information included in the datafeed should be at the product parent level, rather than for individual variants or versions. For example, suppose a Merchant catalog includes the following offerings:
    • Button-down shirt, Black, Large
    • Button-down shirt, Navy, Medium
    • Button-down shirt, Red, Small

    Rather than list all three versions of what is essentially one product, it is preferred that only a single record be included, e.g.

    • Button-down shirt

    In cases where the product pricing varies for the different product versions, we suggest choosing either the lowest or highest price to include in the datafeed. More information on this topic is available below in the Extended Attributes section.

  5. The product SKUs that are supplied in the datafeed should be consistent with what is passed to AvantLink during the tracking phase of an order checkout. This will allow accurate reporting of product details for each order. [This does not apply if you are not passing item details in your order tracking integration.]

Datafeed Retrieval:

AvantLink requires a location to access the datafeed file for daily automated updates. This can be either an HTTP download URL or an FTP server location. Username/password combinations can be included in the datafeed location, as long as no manual user intervention is required.

Datafeed Fields:

Any of the following information may be supplied in a datafeed. If you have additional data you would like to provide affiliates, beyond what is shown in this list, please contact us – we do have the ability to include non-standard attributes in any Merchant datafeed (see Extended Attributes below).

ColumnTypeRequired/OptionalDescription
SKU string required The unique product ID or SKU from your internal e-commerce system.
Manufacturer ID string optional The manufacturer assigned product ID, i.e. manufacturer part number.
Brand Name string recommended The product brand name.
Product Name string required The product name.
Long Description string required The product long description.
Short Description string optional The product short description.
Category string required The category name this product is associated with on your website. Category, Subcategory, and Product Group values need not conform to any global standard; they can be customized as desired to fit your own website.
Subcategory string optional The subcategory name this product is associated with on your website.
Product Group string optional The product group name this product is associated with on your website.
Standardized Categorization string recommended The product categorization according to a global / industry-standard specification. Values must be specified according to theGoogle categorization taxonomy.
Thumb URL string optional The URL for the product thumbnail (a.k.a. small) image. If possible the thumbnail image width should not be greater than 150 pixels.
Image URL string required The URL for the large / full-size product image.
Buy Link string required The product detail page URL.
Keywords string optional A comma delimited list of product keywords.
Reviews string optional Product reviews.
Retail Price decimal required The product price. By default, all currency values should be supplied as US dollars (USD).
Sale Price decimal required The product sale price. $0.00 can be used for products that are not on sale.
Brand Page Link string optional The product brand page URL.
Brand Logo Image string optional The product brand logo image URL.
Item Based Commission decimal optional The item based commission to be paid for this product. Only required if you are doing item based commissions and if the item commission is different then the default program commission amount.
UPC string recommended The 9-13 digit Universal Product Code (UPC) for this product. Often however, UPCs are unique to product color, size, or style variations and may better be specified using a “variants”Extended Attribute rather than one single value per product.

Extended Attributes:

As noted above (see Datafeed Fields), AvantLink has the ability to include non-standard (a.k.a. extended) attributes in any Merchants' datafeed.

One of the more common requests from affiliates for a non-standard attribute is for product version or variant information.
Because our datafeed spec is geared toward a single record per product, e.g.

  • Button-down shirt

rather than all variations of that product, e.g.

  • Button-down shirt, Black, Large
  • Button-down shirt, Navy, Medium
  • Button-down shirt, Red, Small

some of the detailed information that affiliates would like to feature on their sites may be unavailable.

To overcome this limitation, without interfering with normal usage of the datafeed, we recommend that Merchants include product variant information in an extended XML attribute field, as in the following:

<variants>
	<variant>
		<sku>ZOO0241-LB</sku>
		<vendor_sku>10802</vendor_sku>
		<upc>808079337405</upc>
		<color>BLACK</color>
		<size>L</size>
		<detail_url>http://www.abcfoods.com/product.html?id=10802</detail_url>
		<action_url>http://www.abcfoods.com/add_to_cart.html?id=10802</action_url>
	</variant>
	<variant>
		<sku>ZOO0241-MN</sku>
		<vendor_sku>10935</vendor_sku>
		<upc>808079337399</upc>
		<color>NAVY</color>
		<size>M</size>
		<detail_url>http://www.abcfoods.com/product.html?id=10935</detail_url>
		<action_url>http://www.abcfoods.com/add_to_cart.html?id=10935</action_url>
	</variant>
	<variant>
		<sku>ZOO0241-SR</sku>
		<vendor_sku>12618</vendor_sku>
		<upc>808079337382</upc>
		<color>RED</color>
		<size>S</size>
		<detail_url>http://www.abcfoods.com/product.html?id=12618</detail_url>
		<action_url>http://www.abcfoods.com/add_to_cart.html?id=12618</action_url>
	</variant>
</variants>

NOTES:
* Line feeds and indentation have been added for display purposes. These should be stripped out for an actual datafeed file.
* You can name your extended attribute column headers whatever you want. We will map them into standard database fields on our side.
* Variants XML data should be added as a new column to your existing delimited product datafeed file as demonstrated in the sample below.

As with all other information in the datafeed, what to include in this field is subject to what is available. Globally unique identifiers such as the UPC are greatly appreciated by many affiliates however, as they allow relevant product comparisons between merchants. Available sizes, colors, pricing differences, etc. are all good candidates for inclusion in this data as well.

The following is a list of the allowable pieces of information (all of which are optional) which may be included in this field; anything not conforming to this list will be removed:

NodeTypeDescription
sku string The unique Product ID or SKU from your internal e-commerce system for this variation.
upc string The Universal Product Code (UPC) for this variation.
vendor_sku string The manufacturer assigned product ID, i.e. manufacturer part number, for this variation.
size string The size/weight information for this variation.
color string Product variation color details.
style string Product variation style details.
retail_price float The exact price of this variation.
sale_price float The sale price (if on sale) for this variation.
image_url string URL of the variant/child product image if different from the parent product image.
detail_url string URL to product detail page.
action_url string URL to take action (e.g. add to cart) for a specific product variation.

Support:

If you have any questions please contact integration@avantlink.com for help.

Have more questions? Submit a request
Powered by Zendesk