Skip to main content

Product Feed Requirements

Updated

Table of Contents

  1. Preface        
  2. Minimum Data Required    
  3. Update Frequency  
  4. File Encoding  
  5. File Naming Convention    
  6. Supported Formats
  7. Hosting Options

 

1. Preface

To create the best end-to-end experience, Wunderkind needs the coordination of 2 data points (the Product ID and the SKU) across 3 different data sets (the Product Feed, On-Site Tracking, and the Conversion Pixel).

 

Data Points

Product / Item Group ID: an identifier that represents the product independent of all selections/attributes (i.e. no size, color, etc).

Example: you sell a shirt that comes in 4 different colors and 4 different sizes. The Product ID would be the identifier that represents the group of all possible combinations, and you represent this with the identifier “S”

SKU / Variant ID: an identifier that represents the product drilled down to all available specific selections/attributes.

Example: you sell a shirt that comes in 4 different colors (red, blue, gray, and black) and 4 different sizes (S, M, L, XL).  The SKU would be the shirt in Red in a size Large, and you represent this with the identifier S-001-L.

 

Data Sets

Wunderkind needs for the SKU and the Product ID to be consistent across 3 different data input points.

 

Data Input #1: The Product Feed

The Product Feed should have a row for every single SKU.  One of the fields associated with each SKU should be the Product ID.  Please note that some E-Commerce platforms require you to use a 3rd-party feed management tool to compile your product feed (e.g. Shopify).  For more details on the product feed, see sections III - VII of this guide.

 

Data Input #2: On-Site Tracking

The Product ID and the SKU should be readily available for tracking on Product Details, Quickview, Category, Search, and Confirmation Pages.  

 

Data Input #3: Conversion Pixel

For each item passed through the conversion pixel, the object should include both the SKU and the Product ID.  For more details, see the Ecommerce Conversion Multipixel Guide.

 

In Summary

 Data Point SKU / Variant ID Product / Item Group ID
Product Feed Included in each row “ “
On-site tracking On Product Details Pages, Quickview, Category Pages, Search Pages, and Confirmation Pages “ “
Conversion Multipixel Passed through the item object as “sku” Passed through the item object as “product_id”

 

2. Product Feed - Minimum Data Required

Product Information

 

 Data Definition Required
Data Type		 Additional Requirements
Variant ID This identifier will represent the product drilled down to all available specific selections/attributes (aka SKU) string Alphanumeric characters; dashes and
underscores acceptable. Maximum 64 characters.
Product or Group ID This identifier will represent the product ›independent of all selections/attributes (i.e. no size, color, etc). string Alphanumeric characters; dashes and
underscores acceptable. Maximum 64 characters.
Title The title of a product string Title should appear as you would want it displayed to a user in their shopping experience.
Product Page URL A link to the product details page of the product. string Link to SKU-level product is preferred, but link to product group is accepted.
Image URL A link to the image of the product. string Link to SKU-level image is preferred, but link to product group is accepted.
Price Variant's current price on site. String or string with float (e.g. string with float in it examples: “12.00 USD”, “€3.0 EUR”") The feed must use a single currency and it must stay the same day over day.  If other than USD, the currency must be denoted in the feed via an ISO 4217 currency code. See next page for more details.
Available Quantity The number of units available to be purchased online. Integer
or float		 Eg. “4” or “4.0”. See next page for more details.
CategoryNavigation

Required if no separate category file. 

Default category hierarchy delimited

 string Example: “Womens>Shoes>Dress”. Required for Audiences segmentation product.
Product Description A detailed description of the product string UTF-8, no limit on characters. The longer the and more detailed the descriptions the better.

 

Price

Price may be passed as a single field, in which case the following requirements apply:

 Data Definition Required
Data Type		 Additional Requirements
Price Variant's current price on site. String or string with float (e.g. string with float in it examples: “12.00 USD”, “€3.0 EUR”") The feed must use a single currency and it must stay the same day over day.  If other than USD, the currency must be denoted in the feed via an ISO 4217 currency code.

Alternatively, price may be communicated through a set of fields, where the lowest of these prices represents the current price available on site:

 Data Definition Required
Data Type		 Additional Requirements
Original Price Original price of item.
(Does not change.)		 String or string with float (e.g. string with float in it examples: “12.00 USD”, “€3.0 EUR”, 15.00 GBP") The feed must use a single currency and it must stay the same day over day.  If other than USD, the currency must be denoted in the feed via an ISO 4217 currency code.
Promotional Price Temporary sale price.    
Markdown Price Permanent markdown price.    

 

Availability

 Data Definition Required
Data Type		 Additional Requirements
Available Quantity The number of units available to be purchased online. Integer or float

Required for Low In Stock emails.

eg. “4” or “4.0”. If specific quantity values are not available, you may pass three distinct values to represent stock level, eg. 0 = out of stock, 1 = low stock, 2 = in stock, full availability
Availability Availability for online purchase. string

If Available Quantity is not provided. 

Acceptable values (case insensitive) for in stock are ‘true’, 'in stock', 'available for order', and for out of stock are ‘false’, 'preorder', 'out of stock', or 'discontinued'. Snake-case, camel-case, and kebab-case supported. Enables Back in Stock emails.
Availability Date The date the item will be available for purchase. This will be used to designate an item as New. For existing products, leave the field blank or include the past availability date. string

Required for New Product emails. Format should be

yyyy-mm-dd with three character timezone
(eg. “2020-02-19 UTC”)

 

3. Update Frequency

  • Feeds should be updated every 4 hours. At a minimum, they must be updated daily.
  • Feeds should be posted close to the top of the hour, as Wunderkind checks at the top of the hour for a new feed.
  • For instance, posting a feed at 8:45am UTC will result in Wunderkind processing the feed at approximately 9am UTC.

4. File Encoding

  • Feeds must be provided in UTF-8 encoding

5. File Naming Convention

General Requirements

  • File names must leverage UTF-8 encoding.

Feeds with Datestamps or Timestamps (optional)

Note: Date-stamped files are supported with any hosting message. Time-stamped files are only supported on an S3 bucket, FTP, or SFTP (not via direct web link.)

  • Date stamps must articulate the date using the below format.  These can be placed in any order and with any UTF-8 delimiter.
    • 4-digit year
    • Zero-padded 2-digit month
    • Zero-padded 2-digit day
  • Timestamps must be placed at the end of the filename and use 24 hour format
  • Wunderkind can only support product feeds with date or timestamps that utilize UTC time.
  • If using a date-stamped feed, it is preferred that it be uploaded no later than 22:00 UTC for faster processing of the feed and more timely application of the data.
  • Date stamps must not include spaces

6. Supported Formats

General Requirements

  • All feed data files must use UTF-8 encoding.
  • The file must use a single format/delimiter in its entirety.  For example, a file that is partially comma-separated and partially pipe-delimited will not be accepted.
  • Wunderkind supports the following file formats.  
    • .csv: CSV file
    • .tsv: TSV file
    • .txt: Pipe-delimited file
    • .xml: XML (RSS or ATOM)
    • gz: Gnu zip; compressed CSV, TSV, or XML

CSV, TSV, and Pipe-delimited Files

  • The first row specifies the column header. Subsequent rows supply the corresponding values for each route.
  • Fields containing whitespace or commas should be enclosed in "double quotes". Example for a product called The “Absolute Best” Product Ever:  
    • "The ""Absolute Best"" Product Ever"
  • Please limit carriage returns to the end of a field.

XML Files

  • The file must begin with the declaration tag and follow either the RSS or ATOM specification.
    • RSS Structure:
<?xml version="1.0" encoding="UTF-8"?>

<rss version="2.0">

    <channel>

        <title>My Shop Products</title>

        <link>https://www.myshop.foo</link>

        <description>Product feed for Wunderkind</description>

        <item>

            <title>Product 1</title>

            ...

        </item>

        <item>

            ...

        </item>

    </channel>

</rss>

 

ATOM structure

<?xml version="1.0" encoding="UTF-8"?>

<feed xmlns="http://www.w3.org/2005/Atom">

    <title>My Shop Products</title>

    <link>https://www.myshop.foo</link>

    <entry>

        <title>Product 1</title>

        ...

    </entry>

    <entry>

        ...

    </entry>

</feed>

 

When passing null prices via XML, the following formats are acceptable:

  • <price></<price>
  • <price><null/></price>
  • <price xsi:nil="true"/>
  • <price/>

7. Hosting Options

If using FTP, SFTP or S3 bucket, these should be hosted on your own servers.

Direct Link

  • URL to the feed
  • If using HTTPS, the SSL certificates must be
  • Notes: 
    • Wunderkind cannot ingest files with a timestamp on Direct Links.
    • Wunderkind cannot ingest password-protected files via Direct Link.

S3 Bucket

  • User Name
  • Access Key ID
  • Secret Access Key
  • Filepath + File Name
  • Region
  • If using a file with a timestamp or any other filename that relies on our Prefix Match feature, please note that there cannot be more than 1000 files with the same prefix in the bucket, as we will not be able to pull this file due to limits in place by Amazon.

FTP

  • Address
  • Port
  • Username
  • Password
  • File Path + File Name
  • Must allow for more than 1 concurrent connection.
  • If using a file with a timestamp or any other filename that relies on our Prefix Match feature, the LIST command must return in MLST format as defined in RFC 3659.

SFTP

  • Address
  • Port
  • Username
  • Password
  • File Path + File Name
  • Must allow for more than 1 concurrent connection.

Access Requirements

If IPs must be authorized for external access, please see here for a list of Wunderkind IPs.

If credentials are required to access the product feed, you must provide them to Wunderkind. Note that as referenced above, we cannot support password protected files via Direct Link.

 

Appendix A: Optional Data (with Audiences Product only)

These fields are typically used to further identify items for criteria categorization and segmentation purposes. We can also accommodate any other data you feel may be valuable in the remarketing of your product line.

Data Definition Required
Data Type		 Additional Requirements
ISBN Links to essential information used in sales tracking, retail inventory systems, library catalogs, etc. N/A None
UPC Universal product code N/A  
Department If products belong to specific departments N/A Often used for creating custom categories
DaysOld Days product has been available to purchase N/A  
Brand If products are available in multiple brands N/A Often used for custom categories
Gender Provided by user or inferred N/A Often used for custom categories
OnSale or OnClearance Flag to indicate if product is on sale/clearance N/A  
CanBeDiscounted Flag to indicated if item can be discounted N/A  
IsDiscontinued Flag to indicate if item is discontinued N/A  
ExpirationDate Date the product will no longer be available N/A  
UnitsSold Number of products sold to date Integer or float  
AverageRating Average of all user ratings for specific product N/A Used in campaigns requiring the rating of a product on your website
NumberOfRatings Quantity of ratings a product has received integer Used in conjunction with AverageRating

 

 

Related articles

Powered by Zendesk