Page tree

 

Contents

You can upload specific item data into a dataset using the Evergage API. This is useful if you want to add a list of items from your database to your Evergage dataset directly instead of waiting for them populate with specific events. You can also use item upserts to update specific items already in your dataset. This data must be constructed very precisely and submitted to Evergage as a .CSV (Comma Separated Value) file. These files can be created in any spreadsheet program such as MS Excel or Google Sheets. Spreadsheet, etc.).

Sections included in this article

Constructing the .CSV file

When creating the file, ensure that each individual item only occupies one row in the spreadsheet and the first row of the spreadsheet details the specific item attributes being upserted. See the screenshot below for clarification:

 

Required fields

In order to upsert an item, at least two columns must be populated:

  • id: This is the item ID of the product you want to upsert. It's the unique identifier that we'll use to either create a new item, or update an existing one.
  • type: The type identifier lets Evergage know what kind of item it is. There are five possible choices, each represented by a single character:
    • Product: "p"
    • Article: "a"
    • Blog: "b"
    • Category: "c"
    • Tag: "t"

IMPORTANT REQUIREMENTS

It is very important that the itemId field that you upsert is an exact string match to what is naturally seen as events in Evergage. What this means is that if the item being tracked by the beacon (or Visual Editor) is "product1," and in the .CSV file you submit "product 1" for the ID, it will not update the current item but instead create a new one.

Optional Fields

The rest of the fields are optional, and setting them will either set or overwrite the current value. Please note that all fields are case sensitive.

  • name: The name of the product (this is a label, and not the same thing as a unique identifier).
  • locked: Set this to either "true" or "false". If "true", incoming events will not be able to overwrite changes made by this upsert.
  • url: The URL that links to this specific item.
  • imageUrl: The URL that links to this specific item's image.
  • description: The description of this item.
  • archived: Set this to either "true" or "false". If true, it will no longer be promoted. If false or not present in the upsert, it will be.
  • expiration: Set this to an epoch millisecond time stamp. This the that it will stop being promoted.
  • published: Set this to an epoch millisecond time stamp. This is the date that it will start being promoted.
  • location.longlat: This is a coordinate representation of the items longitude and latitude. If applicable to your item (e.g. restaurant location), you can map the longitude and latitude with two separate values delimited by a pipe ("|") character. For example, a restaurant in New York may have a location.longlat as: "73.9|40.7".

The following 5 fields are used to set tag values on the item. You can set multiple tags at once, and the value sent through an upsert will overwrite any tags currently on the product. Tags should be delimited by a pipe ("|") character.

  • brands
  • itemClasses
  • styles
  • authors
  • keywords
  • contentClasses
  • promotions


Item Type Specific Fields

These are optional fields that are unique to a specific type of item. For example, if you set an item's type as "p" (for product), you can set attributes like price or inventory count. Below is a full list of item type specific fields:

Products:

    • price: Set this to a number with up to two decimals. Do not include a currency symbol (e.g. $).
    • alternateId: An alternate unique identifier to the "id" value.
    • isProduct: Set to true or false. Necessary for any product with multiple SKU values.
    • priceDescription: Optional field for descriptive text for the Product price, e.g. 'Sale Price'.
    • listPrice: Optional field for capturing e.g. MSRP in order to illustrate discount.
    • currency: Set to a string. An ISO 4217 currency code. Can be different than your dataset wide setting.
    • inventoryCount: Set to an integer value. The remaining stock count for this product.
    • skus: Set to a pipe separated list of alphanumeric strings (e.g. "sku1|sku2|sku3"). The list of skus for the product. Will not overwrite currently set SKUs but will add new ones if they're not on the product already. Remember to include isProduct as another column when you upsert SKUs.
    • categories: Set to a pipe separated list of alphanumeric strings with ">" indicating subcategories (e.g. "category1|category2|category3>subcategory3"). The list of categories for a product. This WILL override any categories currently on the product. If you upsert a category that is not part of the dataset, a new one will be created.

 

Articles and Blogs:

    • published: Set this to an epoch millisecond time stamp. This is the date the article or blog was published.

      NOTE

      published was formerly called publishedDate

    • modifiedDate: Set this to an epoch millisecond time stamp. This is the date the article or blog was last modified.
    • subtitle: The article or blog subtitle.
    • categories: Set to a pipe separated list of alphanumeric strings (e.g. "category1|category2|category3"). The list of categories for an article or blog. This WILL override any categories currently on the item. If you upsert a category that is not part of the dataset, a new one will be created.

Categories:

    • isDepartment: Set to true or false. If true, this category is considered a top-level department (e.g. "Men's" or "Women's").

 

Tags:

    • TagType: Set this to whichever type of Tag is being updated. Options include "Brand", "ItemClass", "Style", "Author", Keyword". 

 

Example of Sending Item Upsert 

The following example uses curl:

Update Frequency

You may choose the frequency of your catalog updates. Some Evergage customers send this update daily/nightly. Many send us updates more frequently. You may send these updates hourly without any issue. If you wish to send updates more frequently than hourly, this can be arranged but may involve a fee if the volume of data is large enough. Please contact your Evergage Customer Success person to discuss this further. 

 

This page has no comments.