Page tree
Skip to end of metadata
Go to start of metadata

You can import specific catalog item data into a dataset using the Interaction Studio API. This is useful if you want to add catalog items from your database to your Interaction Studio dataset directly instead of waiting for them populate with specific events. You can also use catalog item upserts to update a specific catalog already in your dataset. These import are called "upserts" because if the catalog item is already known to Interaction Studio it is updated, otherwise it is inserted. This data must be constructed very precisely and submitted to Interaction Studio 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.).


Interaction Studio Classic Only

  • The contents of this article are intended for customers using Interaction Studio (formerly Evergage Classic). Do not adjust your beacon version to downgrade or upgrade.
  • If you are a Campaigns & Templates customer, please refer to the CSV Feed Requirements in this knowledge base, or the Feeds article in developer.evergage.com.
  • The Visual Editor Chrome Extension will no longer be available starting January 1, 2023. For more information, see this knowledge article.
This Article Explains

This section details how to import specific catalog item data into a dataset using the Interaction Studio API

Sections in this Article

Constructing the .CSV file

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


Required fields

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

  • id: This is the ID of the catalog item you want to upsert. It's the unique identifier that we'll use to either create a new catalog item, or update an existing one.
  • type: The type identifier lets Interaction Studio know what kind of catalog 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 Interaction Studio. What this means is that if the catalog 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 catalog 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 catalog item.
  • imageUrl: The URL that links to this specific catalog item's image.
  • description: The description of this catalog 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 catalog item's longitude and latitude. If applicable to your catalog 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 catalog 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


Catalog Item Type Specific Fields

These are optional fields that are unique to a specific type of catalog item. For example, if you set a catalog item's type as "p" (for product), you can set attributes like price or inventory count. Below is a full list of catalog 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 catalog 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", "Gender", etc.


Example of Sending a Catalog Item Upsert 

The following example uses curl:

export ACCOUNT='accountName'
export DATASET='datasetName'
export UPSERT_FILENAME='itemUpsert.csv'
export HTTP_BASIC_AUTH_STRING='QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc='

curl -k -X POST -F "file=@${UPSERT_FILENAME}" -H "Authorization: Basic ${HTTP_BASIC_AUTH_STRING}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/items/upsert"
 

Update Frequency

You may choose the frequency of your catalog updates. Some Interaction Studio 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. Please contact your account representative to discuss this further.