Table of Contents
- Preface
- Minimum Data Required
- Update Frequency
- File Encoding
- File Naming Convention
- Supported Formats
- 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 |
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
- Valid,
- Verifiable, and
- Have their intermediary cert chain configured correctly.
- You can test this with: https://www.ssllabs.com/ssltest/
-
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 |