(888) 310-0589 x2
You can import specific catalog item data into a dataset using the Evergage API. This is useful if you want to add catalog items from your database to your Evergage 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 Evergage it is updated, otherwise it is inserted. 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.).
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:
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 Evergage 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"
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 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.
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.
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:
- 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.
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.
- isDepartment: Set to true or false. If true, this category is considered a top-level department (e.g. "Men's" or "Women's").
- 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:
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.