Dynamic Yield Developer Documentation

Browse Dynamic Yield's latest developer documentation including API references, articles, and sample code for optimizing, personalizing, and creating consistent digital customer experiences across touchpoints.

Get Started    

Uploading a Product Feed

👍

What's in this page

This is a concise version of the article on Data Feeds in our Knowledge Base, which is available only to logged-in customers. This article describes only the common use case of synchronizing an eCommerce Product Feed through a URL, with typical settings.

For other feed types, verticals, and advanced functionality such as multi-language support and custom parser functions, please refer to the full article.

If you're building an eCommerce store, synchronizing your product feed with Dynamic Yield is a must. It's the basis for using recommendations, defining audience groups and targeting rules, using social proof features, and much more.

The most common method for making your feed available to Dynamic Yield is through an HTTP/S URL that you specify. This resource is typically secured via HTTP basic authentication over HTTPS, and/or limiting your firewall ingress rules to only allow our outbound IPs access to the file. For alternative methods, please contact us.

Feed Formats and Sizes

Each site can have one product feed defined, but that feed can be an aggregation of multiple source URLs. Functionality and supported formats differ by the feed size:

Feeds up to 25MB and 20,000 products

All feed features are supported:

  • Supported formats are: CSV (comma separated), JSON, or XML.
  • Periodic synchronization is supported for frequencies as low as every five minutes.
  • Custom Parser functions are supported: You can supply a custom JavaScript function to transform from whatever structure your source data is - into our list of required fields and their types. For XML feeds, a parser function is always required. Parser functions can emit products based on the aggregation of multiple source lines and multiple sources.
  • A feed file up to 25MB may be uploaded directly via the UI. This enables you to start validating a feed format and developing features dependent on this feed, even prior to setting up a URL for your current feed.

Feeds up to 180 MB and 200,000 products

Feeds of this size support the same features as above, but minimum synchronization frequency is 1 hour.

Larger feeds of up to 1GB and 2 million products

  • Format must be CSV.
  • Parser functions are not supported, meaning the link you set should point to a file that needs no more transformations.
  • Minimum synchronization frequency is 6 hours (but you can use our API for quick updates).

Here's how that choice is made in the Admin UI:

Fields

Notes

1. Required field names are listed below. Names are case-sensitive (all lower-case). All products should have values set for all required fields. If a required value is missing, a warning will be added to the log (downloadable through the Admin UI) and that product will be skipped.

2. Optional fields (keywords field, custom fields, and per-language translation columns) do not need to have values for every product.

3. Custom fields can be added to the feed at any time but generally should not be deleted - as this can lead to missing data and broken experiences.

Required Fields

Field name (case sensitive)DescriptionValue FormatExample
skuA unique identifier for the productString - without spaces"bg10087-301"
group_idA unique identifier for a group of variants of the same product, which typically only differ by a single attribute (e.g. color).
If there is no group for this product, simply use the product SKU
String - without spaces"bg10087"
nameProduct Display NameString"Plaid Reloaded Shirt"
urlLink to the product details page (on the web). Must be a valid URL starting with HTTP/S, usually to the canonical URL for the product.
Often, a group of variants shares the same URL, which always displays the default variant first
String URL"https://www.shopthis.co/products/plaid-reloaded-shirt-bg10087"
pricePrice of the product in the site's currency.
Additional per-locale prices are supported - see multi-language support
Float9.5
in_stockWhether the product is currently in stock. Out of stock products are never included in recommendationsBooleantrue / false
image_urlLink to the product image. Must be a valid URL starting with HTTP/SString URL"https://images.shopthis.co/products/plaid-reloaded-shirt-bg10087_big.png"
categoriesA list of the categories associated with the product, from the most generic to the most specificString: pipe-separated list of categories. No extra spaces are needed"Women’s|Trousers & Jeans|Chinos”

Optional Fields

Field name (case sensitive)DescriptionValue FormatExample
keywordsOptional but strongly recommended: any additional information describing the product, separated by the pipe character. If available, used by our recommendations engine and affinity-based featuresString: pipe-separated list of keywords. No extra spaces are needed"Bohemian|Casual|Collector's Item"
Custom column name: any string, e.g. "age_group", "on_sale" etc.You can add up to 30 additional fields to the feed. Special characters in the name are not supportedString."Some custom value,"
"Ages 35-45"

For details on support for multi-locale fields, please visit the Knowledge Base article.

Examples

Here's a simple CSV-formatted feed with only the required fields, and no groups:

sku,group_id,name,in_stock,price,image_url,url,categories
100,100,Plaid Reloaded Shirt,true,29.50,https://img.sh.op/p100.png,https://sh.op/p/p100.html,Men's|Smart Casual
101,101,Sweat It Shirt,false,19.90,https://img.sh.op/p101.png,https://sh.op/p/p101.html,Men's|Sports

Here's the same in JSON format:

[
  {
    "sku": "100",
    "group_id": "100",
    "name": "Plaid Reloaded Shirt",
    "in_stock": true,
    "price": 29.50,
    "image_url": "https://img.sh.op/p100.png",
    "url": "https://sh.op/p/p100.html",
    "categories": "Men's|Smart Casual"
  },
  {
    "sku": "101",
    "group_id": "101",
    "name": "Sweat It Shirt",
    "price": 19.90,
    "in_stock": false,
    "image_url": "https://img.sh.op/p101.png",
    "url": "https://sh.op/p/p101.html",
    "categories": "Men's|Sports"
  }  
]

Here's a feed with groups and optional fields:

sku,group_id,name,in_stock,price,image_url,url,categories,keywords,color,age_group
200-10,200,Monday Again Shirt,true,29.50,https://img.sh.op/p200-10.png,https://sh.op/p/p200.html,Women's|Smart Casual,Work|After Work,White,21-35
200-20,200,Monday Again Shirt,false,29.50,https://img.sh.op/p200-20.png,https://sh.op/p/p200.html,Women's|Smart Casual,Work|After Work,Black,21-35
200-30,200,Monday Again Shirt,true,34.50,https://img.sh.op/p200-30.png,https://sh.op/p/p100.html,Women's|Smart Casual,Work|After Work,Teal,21-35
201-10,201,Ultimate Chair III,true,299.50,https://img.sh.op/p201-10.png,https://sh.op/p/p201.html,Office|Chairs

For a live example, please follow the "Petshop" tutorial.

Updated about a year ago


Uploading a Product Feed


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.