Skip to end of metadata
Go to start of metadata

 Evergage ETL supports the ingestion of feed files delivered to the Evergage SFTP site. Users, transactions, products, categories and custom dimension feeds are supported out of the box with the following formats. Feed file formats best support multi-channel operation when there are user identities that can be matched with the Evergage identity resolution system. Catalog and transaction feeds best support multi-channel operation when identities for online and offline product and dimension identities match.

This Article Explains

This article details the requirements and schema for the feeds supported by the Evergage ETL.

Sections in this Article

Accepted Formats

This document applies for RFC-41806 CSV based formats. Character encoding must be UTF-8. All max lengths are in UTF-8 encoded bytes. Submitted content must be internally consistent. Conflicting metadata definitions will produce unexpected results. Files can also be compressed using gzip and named *.gz instead of *.csv.


User Data Feeds

Evergage stores user profiles for each anonymous and named user in the system. These users can represent users of any Evergage supported channels including web, mobile, email and in store. Custom attributes may be defined for user profiles with types and additional fields can be imported to those attributes with additional columns. Custom attribute names should match the column names of those additional fields.

File Name Format: user-YYYY-MM-DD:HH-MM-SS.csv

Requirements and Schema

Field Name

Minimum RequirementsExample Values

Max Length

userId

Optional. Must match the format of the configured default user ID type for this feed. Since a user can have multiple identities, user ids can also be constructed from other identifying information in the record (emailAddress, attributes or other userId: fields). If none of these methods result in a user ID, this record will not be loaded.

jdoe
john.doe@example.com
c2e384084c8ac233
120

userId:

Optional. Column titles are the word 'userId' followed by colon followed by the user ID type. Values must match the format of the specified user ID type. Otherwise, processed like userId.
"userId:named", "userId:marketoId"
"jdoe", "29237102"
120
accountIdOptional. If provided, a string value of the account ID to associate with the user. Must be lowercase. This is only available with Evergage B2B functionality enabled. Contact your customer success representative for details.
example industries
example.com
120
displayNameOptional. Display name for user
Bob Newhart
John Standard
1023
emailAddressOptional. Valid email address. If provided, used as a user identity of the type emailAddress.
user@example.com
bob.smith@example.com
1023
attribute:

Optional. The custom attributes for this user. Column titles are the word 'attribute' followed by colon followed by the attribute name. Attributes are singled-valued and always interpreted as strings. Attributes can be used to construct user ids.

"attribute:lastname", "attribute:firstname"
"Gina", "Torres"
1023

Transaction Data Feeds

Evergage supports the ingesting of transactions. These transactions may be historical or current transactions. Transactions may be updated by sending new transactions with the same transactionID. Transaction attribution to Evergage campaign reporting happens based on the timestamp in the feed and not the time of the ingestion.

File Name Format: transaction-YYYY-MM-DD:HH-MM-SS.csv

Requirements and Schema

Field NameMinimum RequirementsExample ValuesMax Length
transactionIdRequired. A unique transaction ID must be included. If orders are also being tracked by Evergage on site the two transaction IDs must match. This transaction ID can be used to avoid tracking the same transaction twice even if it is received twice. Transaction IDs are case-sensitive. All rows with the same transaction ID must appear consecutively.
014323919230412
255
dateRequired. An ISO 86011 fixed, unchanging date and time that this transaction took place. Subsequent mentions of this transaction in any subsequent feed files must not change the transaction date for an existing transaction ID.
2017-04-22T10:23:37Z

userIdOptional. Must match the format of the configured default user ID type for this feed. Since a user can have multiple identities, user ids can also be constructed from other identifying information in the record (emailAddress, attributes or other userId: fields). If none of these methods result in a user ID, this record will not be loaded.
jdoe
john.doe@example.com
c2e384084c8ac233
120
userId:Optional. Column titles are the word 'userId' followed by colon followed by the user ID type. Values must match the format of the specified user ID type. Otherwise, processed like userId.
"userId:named", "userId:marketoId"
"jdoe", "29237102"
120
emailAddressOptional. Valid email address. If provided, used as a user identity of the type emailAddress.
user@example.com
bob.smith@example.com
1023
productId

Required. Product IDs must exactly match the product IDs provided on site and captured by Evergage catalog mapping. Product IDs are case-sensitive.

Examples of unacceptable identifiers:

  • product name
  • product ID in a different format
  • an inventory ID that is not used by Evergage to track on site
prod123abc
255
priceRequired. The unit price the user was charged. Period as the decimal separator, no thousands separator. This will be multiplied by the quantity to determine the total value of this line item. For instance, if price is $1.10 and quantity is 3, the total value of the line item is $3.30.
17.22

quantityRequired whenever one or more units are purchased. This is the net quantity purchased. If only purchases are tracked, this is just the number of units purchased. Otherwise, this is the quantity purchased and not yet returned, canceled, etc. If the same line item is updated multiple times, always provide the most current value here, not the change. If the value is unknown, leave this field empty.
3

quantity:returnedOptional. This is the number of units for this line item that were purchased and later returned. If the same line item is updated multiple times, always provide the most current value here, not the change. If the value is unknown, leave this field empty.
1
transactionStatusOptional. Transaction status can be provided to cancel previous orders. Possible values are "open", "purchased", "canceled".
canceled

shipStatusOptional. Status on the delivery of an order to a customer. Allowed values are "processing", "shipped", "delivered".
delivered

attribute:Optional. The custom attributes for this transaction. Column titles are the word 'attribute' followed by colon followed by the attribute name. Attributes are singled-valued and always interpreted as strings. Attributes can be used to construct user ids.
"attribute:name", "attribute:shipAddress"
"Ron Glass", "212 Elms St. Somerville, MA"
1023

Product Data Feeds

Evergage supports ingesting of products into the catalog. Products may be updated by sending new products with the same productID.

File Name Format: product-YYYY-MM-DD:HH-MM-SS.csv or product-us_EN-YYYY-MM-DD:HH-MM-SS.csv (see locale field)

Requirements and Schema

Field NameMinimum RequirementsExample ValuesMax Length
id

Required. Product IDs must exactly match the product IDs provided on site and captured by Evergage catalog mapping.

Examples of unacceptable identifiers:

  • product name
  • product ID in a different format
  • an inventory ID that is not used by Evergage to track on site

Product IDs must appear at most once in the product feed. Duplicate appearances of product IDs will produce unexpected results.

IDs must represent unique products and not unique SKUs.

prod1237723
255
nameRequired. Must contain at least one alphanumeric character.
Slick New Kicks
1023
urlRequired. RFC-39863 Complete URLs that represent the canonical product display page for this product.
https://example.com/products/prod1.html
1023
imageUrlRequired. RFC-39863 Fully-qualified URL for an image of this item.
https://example.com/img/img1.png
1023
priceRequired. The current offer price of this product to promote to users. Period as the decimal separator, no thousands separator.
22.72

listPrice

Optional. A list price or MSRP to illustrate the savings when compared with the price. Period as the decimal separator, no thousands separator.

30.30

marginOptional. The profit margin of the item. Sale price - current cost of goods. Period as the decimal separator, no thousands separator.
2.45

currencyOptional. ISO 42174 Currency Code. Uppercase.
USD
1023
priceDescriptionOptional. Descriptive text for the price.
On sale this week only
1023
categoriesOptional. Category id paths are delimited with > characters. Multiple categories may be defined via pipe delimiting. A literal pipe in one of the values is represented as two pipe characters in the feed.
Home>Bedroom|Home>Bathroom
1023
inventoryCountRecommended. A count of product inventory. 0 count is considered out of stock and not-promotable in product recommendations.
30

descriptionOptional. Must contain at least one alphanumeric character, with a maximum of 250 characters.
Some excellent new shoes
1023
dimension:Optional. Additional dimensions such as brand and color may be defined and imported with matching column names. Each dimension name must match one configured in the Catalog Setup within the Evergage platform. Column titles are the word 'dimension' followed by colon followed by the attribute name. A product can have multiple dimensions in separate columns. A product can have multiple values for the same dimension, separated by the pipe character. A literal pipe in one of the values is represented as two pipe characters in the feed.
"dimension:Color", "dimension:Material"
"Blue|Yellow", "Leather"
1023
publishedOptional. ISO 86011 Date time string for published date.
2017-04-22T10:23:37Z

expirationOptional. ISO 86011 Date time string for product expiration date.
2017-04-22T10:23:37Z

skus

Optional. 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
1023
locationOptional. Space-delimited ISO 67095 Geographic Point Location
35.89421911 139.94637467
1023
promotableOptional. Boolean. Is this product allowed to be shown in recommendations?
true
false

attribute:Optional. The custom attributes for this product. Column titles are the word 'attribute' followed by colon followed by the attribute name. Attributes are singled-valued and always interpreted as strings. Custom attributes must be pre-configured in the Catalog Setup pages before they may be ingested.
"attribute:fit", "attribute:length"
"loose", "long"
1023
locale

Optional. An ISO 639 alpha-2 language code followed by an underscore followed by an ISO 3166 alpha-2 country code.

To provide localized content, create a feed file per locale. Add the locale column to each feed. In the feed for the dataset primary locale, provide full product information. In the locale-specific feeds provide only the fields whose values differ depending on the locale. The dataset primary locale is configured in Catalog Setup.

en_US
ja_JP
5

SKU Data Feeds

Evergage supports the ingesting of product SKUs into the catalog. SKUs may be updated by sending new SKU with the same skuID. SKUs can not switch parent productIDs via feeds.

File Name Format: sku-YYYY-MM-DD:HH-MM-SS.csv or sku-us_EN-YYYY-MM-DD:HH-MM-SS.csv (see locale field)

Requirements and Schema

Field NameMinimum RequirementsExample ValuesMax Length
id

Required. Product IDs must exactly match the product IDs provided on site and captured by Evergage catalog mapping.

Examples of unacceptable identifiers:

  • product name
  • product ID in a different format
  • an inventory ID that is not used by Evergage to track on site

Product IDs must appear at most once in the product feed. Duplicate appearances of product IDs will produce unexpected results.

IDs must represent unique products and not unique SKUs.

prod1237723
255
productId

Required. Product id of the parent product. All SKUs with the same product id must appear consecutively.

prod123
1023
urlOptional. RFC-39863 Complete URLs that represent the canonical product display page for this product.
https://example.com/products/prod1.html
1023
imageUrlOptional. RFC-39863 Fully-qualified URL for an image of this item.
https://example.com/img/img1.png
1023
priceOptional. The current offer price of this product to promote to users. Period as the decimal separator, no thousands separator.
22.72

listPrice

Optional. A list price or MSRP to illustrate the savings when compared with the price. Period as the decimal separator, no thousands separator.

30.30

marginOptional. The profit margin of the item. Sale price - current cost of goods. Period as the decimal separator, no thousands separator.
2.45

currencyOptional. ISO 42174 Currency Code. Uppercase.
USD
1023
priceDescriptionOptional. Descriptive text for the price.
On sale this week only
1023
inventoryCountOptional. A count of product inventory. 0 count is considered out of stock and not-promotable in product recommendations.
30

dimension:Optional. Additional dimensions such as brand and color may be defined and imported with matching column names. Each dimension name must match one configured in the Catalog Setup within the Evergage platform. Column titles are the word 'dimension' followed by colon followed by the attribute name. A product can have multiple dimensions in separate columns. A product can have multiple values for the same dimension, separated by the pipe character. A literal pipe in one of the values is represented as two pipe characters in the feed.
"dimension:Color"
"Blue"
1023
promotableOptional. Boolean. Is this product allowed to be shown in recommendations?
true
false

attribute:Optional. The custom attributes for this product. Column titles are the word 'attribute' followed by colon followed by the attribute name. Attributes are singled-valued and always interpreted as strings. Custom attributes must be pre-configured in the Catalog Setup pages before they may be ingested.
"attribute:fit", "attribute:length"
"loose", "long"
1023
locale

Optional. An ISO 639 alpha-2 language code followed by an underscore followed by an ISO 3166 alpha-2 country code.

To provide localized content, create a feed file per locale. Add the locale column to each feed. In the feed for the dataset primary locale, provide full product information. In the locale-specific feeds provide only the fields whose values differ depending on the locale. The dataset primary locale is configured in Catalog Setup.

en_US
ja_JP
5

Category Data Feeds

Evergage supports ingesting categories.  Categories can be updated by exactly matching on the categoryId for the category to update.

File Name Format: category-YYYY-MM-DD:HH-MM-SS.csv 

Requirements and Schema

Field NameMinimum RequirementsExample ValuesMax Length
categoryId

Required. Category IDs must exactly match the same type of identifier that is transmitted for category IDs in the Evergage site beacon integration and in the product feed. Specifically, the exact category ID must be available on the site, such that the Evergage beacon can include it.

Examples of unacceptable identifiers:

  • category name
  • a category ID that is not accessible by the Evergage site beacon integration

Category IDs must appear at most once in the category feed.

12336
255
parentCategoryId

Required. Parent category IDs must be of the same exact format and values as the IDs used in the categoryId field.

Root categories exception: an empty value or value of 0 is acceptable when a category has no parent.

All categories with the same parent category ID must appear consecutively.

3356
255
nameRequired. Must contain at least one alphanumeric character.
Chelsea Tee
1023
urlOptional. RFC-39863 Complete URL that represents the canonical category description or listing page for this category.
http://www.example.com/c/mens/shirts/tees
1023
imageUrlOptional. RFC-39863 Complete URL representing the image of this item.
http://www.example.com/images/12336.png
1023
departmentOptional. Boolean. Is this category referred to as a "Department", or "Top Level Category"?
true
false

true

false

Custom Dimension Feeds

Custom dimensions may be defined with additional attribute values that are not part of related feed files. For example, a store feed could include information such as store address and other relevant metadata to be imported into the store dimension. Custom dimensions may be defined within the catalog setup pages or by Gears and can include specific custom attributes. When sending a custom dimension feed, each dimension must be in a separate file.

File Name Format: dimension-store-YYYY-MM-DD:HH-MM-SS.csv or dimension-brand-us_EN-YYYY-MM-DD:HH-MM-SS.csv (see locale field)

Requirements and Schema

Field NameMinimum RequirementsExample ValuesMax Length
id

Required. IDs must exactly match the same type of identifier that is transmitted in the Evergage site beacon integration.

IDs must appear at most once in the category feed.

store123
255
dimensionId

Required. The dimension that this row belongs to.

This must exactly match the name of the dimension specified in catalog setup.

Store
255
nameRequired. Must contain at least one alphanumeric character.
Fresh Pond Mall
1023
urlOptional. RFC-39863 Complete URL for this item.
http://www.example.com/stores/1234
1023
imageUrlOptional. RFC-39863 Complete URL representing the image of this item.
http://www.example.com/images/1234.png
1023
locationOptional. Space-delimited ISO 67095 Geographic Point Location
35.89421911 139.94637467
1023
addressOptional. Street address
24 Bullhorn Rd
1023
cityOptional. City
Boston
255
stateOptional. State
MA
255
postalCodeOptional. Postal Code
02210
255
countryCodeOptional. An ISO 3166-1 alpha-22 country code (e.g. "US")
US
2
attribute:

Optional. Column titles are the word 'attribute' followed by colon followed by the attribute name. Attributes are singled-valued and always interpreted as strings. Custom attributes must be pre-configured in the Catalog Setup pages before they may be ingested.

"attribute:phoneNumber"
"555-456-1212"
1023
locale

Optional. An ISO 639 alpha-2 language code followed by an underscore followed by an ISO 3166 alpha-2 country code.

To provide localized content, create a feed file per locale. Add the locale column to each feed. In the feed for the dataset primary locale, provide full product information. In the locale-specific feeds provide only the fields whose values differ depending on the locale. The dataset primary locale is configured in Catalog Setup.

en_US
ja_JP
5

References

  1. ISO 8601: Data elements and interchange formats – Information interchange – Representation of dates and times - https://www.iso.org/iso-8601-date-and-time-format.html
  2. ISO 3166-1_alpha-2: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
  3. RFC 3986: Uniform Resource Identifier (URI) Generic Syntax - https://tools.ietf.org/html/rfc3986
  4. ISO 4217: Currency Code - https://en.wikipedia.org/wiki/ISO_4217
  5. ISO 6709: Standard representation of geographic point location by coordinates - https://en.wikipedia.org/wiki/ISO_6709
  6. RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files – https://tools.ietf.org/html/rfc4180#section-2