Interaction Studio supports ingesting of products into the catalog. Products may be updated by sending updated products with the same product ID. Products may be added by sending new products with a new product ID. This means that if you include a product with an ID that is not currently in the catalog, the product will be added to the catalog by the feed. Products are configured on the Catalog and Profile Objects Setup screen where you can assign related catalog objects and define custom attributes on the product data type. Existing system fields pertaining to products include, but are not limited to:
- Name - the name of the product
- URL - the qualified product url on the website
- Price - the current offer price of the item
All system fields are declared in the table below.
This article details the requirements and schema of the product ETL and provides a sample file structure and download.
Requirements and Schema
- Each product should appear only once in a single record in any given file. If your file has multiple records with the same product ID, the last valid record in the file will be loaded into Interaction Studio.
- If a column is included in the file, all records in the file should have a value for that column (not just the records whose values have changed). Interaction Studio will overwrite existing values for any changed product records, including those that have blank values.
- Location is a special type of catalog attribute available to products. To help denote where a product may be located, information such as geographic point (latitude and longitude), country code, city, and state can be stored as system attributes. Location fields are not required and only latitude and longitude are codependent. Any other combination of defined location fields are acceptable.
File Format
File Name Format: product-YYYY-MM-DD_HH-MM-SS.csv
Requirements and Schema
See the Sample File section below for further clarification.
Field Name | Minimum Requirements | Example Values | Max Length | Interaction Studio Data Type |
---|---|---|---|---|
id | Required. Product IDs must exactly match the product IDs provided on site and captured by Interaction Studio site mapping. Examples of unacceptable identifiers include: product name, product ID in a different format, and an inventory ID that is not used by Interaction Studio for on site tracking. These are also the parent identifiers of SKUs in the feed. IDs are only expected once per feed. When multiples of the same product IDs are encountered in the same feed, only the contents of the last row will be written to the Interaction Studio catalog. | prod1237723 | 255 | String |
attribute: | The custom attributes for the product. Column titles are the word 'attribute', followed by a colon, followed by the attribute name as configured in the Attributes section of the Catalog and Profile Objects > Product screen. Attributes are parsed as the data type they are defined as in Attributes. | attribute:fit, attribute:length loose, long | 1023 | any |
relatedCatalogObject: | Additional relatedCatalogObjects such as brand and color may be defined and imported with matching column names. Each relatedCatalogObject name must match a catalog object type configured on the Interaction Studio Catalog and Profile objects screen. Column titles are the word 'relatedCatalogObject', followed by a colon, followed by the catalog object type name. A product can have multiple related catalog objects in separate columns and/or multiple values for the same related catalog object, separated by the pipe character. A literal pipe in one of the values is represented as two pipe characters in the feed. Related Catalog Objects & Dimensions For customers leveraging a product ETL configured prior to 9/7/2021 that uses "dimension:" instead of the new "relatedCatalogObject:" column header, this ETL configuration will continue to function as is. The "dimension:" column header will update the Related Catalog Object fields on the product. No changes to the ETL file are required. It is recommended that any new file leverage the updated nomenclature. | relatedCatalogObject:Color relatedCatalogObject:Material Blue|Yellow, Leather | 255 | String |
categories | Multiple categories may be defined using pipe delimiting | Home|Bedroom|Bathroom | 255 | String |
skus | The set of SKUs for this product, separated by the pipe character. A literal pipe in one of the values is represented as two pipe characters in the feed. SKUs are case-sensitive. This is typically used when all SKUs share the same product information. | sku104272|sku32342|sku33388 | 255 | String |
System Fields | ||||
attribute:name | Represents the name of a product and must contain at least one alphanumeric character. | Slick New Kicks | 1023 | String |
attribute:url | RFC-3986 Complete URLs that represent the canonical product display page for this product. | https://example.com/products/prod1.html | 1023 | String |
attribute:imageUrl | Fully-qualified URL for an image of this item. | https://example.com/img/img1.png | 1023 | String |
attribute:description | Represents the description of the product and must contain at least one alphanumeric character. | Some excellent new shoes | 250 | String |
attribute:promotable | Boolean (defaults to true) - when false, the item won't be returned by the Einstein Recipes recommendation system. Note: if no value is set, this field defaults to true. | TRUE | 1023 | Boolean |
attribute:price | The current offer price of this product to promote to users. Period as the decimal separator, no thousands separator. | 20.11 | 1023 | Decimal/Float |
attribute:listPrice | A list price or MSRP to illustrate the savings when compared with the price. Period as the decimal separator, no thousands separator. | 30.3 | 1023 | Decimal/Float |
attribute:priceDescription | Descriptive text for the price. | On sale this week only | 1023 | String |
attribute:margin | The profit margin of the item. Sale price - current cost of goods. Period as the decimal separator, no thousands separator. | 2.45 1000.67 | 1023 | String |
attribute:inventoryCount | InventoryCount: A count of product inventory. 0 count is considered out-of-stock and not promotable in product recommendations. Note: If this value is omitted, the field defaults to in-stock (1). | 30 | 1023 | Integer |
attribute:published | ISO 8601 Date time string for product published date. | 2017-04-22T10:23:37Z | 1023 | Date |
attribute:expiration | ISO 8601 Date time string for product expiration date. | 2017-04-22T10:23:37Z | 1023 | Date |
attribute:currency | ISO 4217 formatted Currency code. 3 Uppercase letters. | USD, AUD, EUR | 3 | String |
attribute:rating | The rating value associated with a product, no specific scale required, however only the value should be provided. 9/10 is invalid, while 9 is. | 4.5 | 1023 | Decimal/Float |
attribute:numRatings | The number of ratings associated with a product. | 5 | 1023 | Integer |
location:latitude | Required if latitude - The exact latitudinal value of the product. | -73.984702 | 1023 | Decimal/Float |
location:longitude | Required if longitude - The exact longitudinal value of the product. | 40.754621 | 1023 | Decimal/Float |
location:city | String value reflecting the name of the city/town/village/etc where the product is located. | New York | 1023 | String |
location:state | The state or region where the product is located. If inside the United States then it is recommended that you use a two-character postal code abbreviation (i.e. "MA" for Massachusetts). | NY | 2 | String |
location:countryCode | An ISO 3166 alpha-2 representation of the country in which the product resides. | US | 2 | String |
location:postalCode | A string-based representation of the postal code where the product is available. | 10036 | 1023 | String |
attribute:archived | Boolean, which defaults to false when no value is set. When true, the item will not be visible in the catalog. If this column is omitted from the feed file, no changes will be made to the archived attribute. | FALSE, false, TRUE, true | 1023 | Boolean |
Sample File
id | attribute:name | attribute:archived | attribute:url | attribute:imageUrl | attribute:price | attribute:listPrice | attribute:inventoryCount | attribute:description | attribute:currency | attribute:formattedPrice | relatedCatalogObject:SaleStatus | relatedCatalogObject:Gender | categories | skus | location:latitude | location:longitude | location:city | location:state |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
prod001 | Glasses | FALSE | http://www.sample.com/products/product001 | http://www.sample.com/image/product001.jpg | 100.12 | 100.12 | 1 | Glasses made to block blinding light | USD | Now $100.12 | OnSale | Men | Clothing|Outerwear | sku1000|sku1001|sku1002 | 47.97522 | 113.62209 | ||
prod002 | Jacket | FALSE | http://www.sample.com/products/product002 | http://www.sample.com/image/product002.jpg | 54.63 | 59 | 1 | A black leather jacket | USD | OnSale | Men|Women|Unisex | Clothing|Outerwear|Leather | 29.05123 | 31.20870 | ||||
prod003 | Shirt | FALSE | http://www.sample.com/products/product003 | http://www.sample.com/image/product003.jpg | 10 | 1 | A blue polo shirt | AUD | Now $10 | Unisex | Clothing|Shirt | sku2000|sku2002|sku2004 | -14.63321 | 14.32845 | ||||
prod003 | Shorts | FALSE | http://www.sample.com/products/product004 | http://www.sample.com/image/product004.jpg | 33 | 60 | 1 | Beige khaki shorts | EUR | Now €33 | OnSale | Men | Clothing|Pants|Shorts | sku300|sku301|sku302|sku399 | -19.63486 | 142.05087 | ||
prod004 | Pants | FALSE | http://www.sample.com/products/product005 | http://www.sample.com/image/product005.jpg | 99.98 | 120 | 0 | Blue jeans | USD | Now $99.98 | ClosingSale | Men | Clothing|Pants | sku401|sku403|sku411 | Seattle | WA | ||
prod005 | Shoes | FALSE | http://www.sample.com/products/product006 | http://www.sample.com/image/product006.jpg | 54.63 | 96.85 | 0 | Brown leather shoes | CAD | Now $54.63 | OnSale | Women | Shoes|Clothing|Leather | sku500 | San Francisco | CA | ||
prod006 | Hat | FALSE | http://www.sample.com/products/product007 | http://www.sample.com/image/product007.jpg | 32.50 | 49.99 | Adjustable baseball cap | DKK | Now 32.50Kr. | OnSale | Kids | Clothing|Accessories | sku610|sku620|sku630 | TX | ||||
prod007 | Watch | FALSE | http://www.sample.com/products/product008 | http://www.sample.com/image/product008.jpg | 10.55 | 10.55 | 1 | Luxury watch | KRW | Now ₩10.55 | NotOnSale | Women | Accessories | Charlotte |