Products

Introduction

When updating Products via file upload, every file is a full sync between your product database and the uploaded file:

• For each product in your file the corresponding product is updated or created in the CrossEngage product database (if the record in the CrossEngage database is older than your file).

• Products not in your file will be removed from the CrossEngage database (if the record in the CrossEngage database is older than your file).

• All products in the CrossEngage database which have an update timestamp newer than the file will be kept and not updated.

Naming Convention

The naming convention of the file is as follows:

product_feed_YYYYMMDDhhmmss.json.gzip

Example:

product_feed_20200324100002.json.gzip

The date in the file name is important as it is used to determine its recency (and therefore whether to update products or not). The timestamp has to be in UTC. As an example, imagine the CrossEngage database currently holds two products:

• SKU-1 last updated on 2020-03-24 07:00:00

• SKU-2 last updated on 2020-03-24 10:34:00

In the above example, processing the file will update SKU-1 because its last update timestamp is older than the file. SKU-2 will not be touched because its last update timestamp is newer than the file.

This is done to resolve conflicts between API updates and feed file uploads and also to determine when to ignore a file – see below.

Please note that the product feed upload needs to be a full data upload instead of delta upload.

File Structure

The data file must contain an array of the products to be loaded into the CrossEngage database. The only mandatory field is sku (stock keeping unit) which is the main product identifier in CrossEngage. Each product can also be assigned to a businessUnit but this is optional. Product feeds without a business unit are also perfectly valid. The combination of SKU and business unit has to be unique for a product.

Properties

Name	Data Type	Description
sku	String	The stock keeping unit of a product (required)
businessUnit	String	Business unit a product belongs to
id	String	Identifiers other than SKU which you would like to pass on to CrossEngage can be submitted through this field. This is a simple text field cannot be used as a CrossEngage product identifier
title	String	The product name
description	String	A description of the product
link	String	The full URL to a product page
bigImageLink	String	The full URL of a high resolution image of the product
smallImageLink	String	The full URL of a thumbnail image of the product
category	String	The category of a product. Can be used for a single category or for combining multiple categories in a single string, for example using breadcrumbs style: Clothes → Jeans
price	Double	Price of a product (without currency)
salesPrice	Double	Can be used to store the advertised sale price of a product. This is a simple numeric field, CrossEngage does not assign any internal logic to it
salesPriceEffectiveDate	String	Date from which the salesPrice applies. No logic is assigned to this field
discount	String	A human-readable description of the discount on the salesPrice (for example €20 or -20%)
currency	String	Currency of the numeric price values
stockQuantity	Integer	Number of items in stock
enabled	Integer	Can be used to mark products as enabled (1) or disabled (0). No internal logic is assigned to this field.
attributes	Object	An object to store custom attributes. At the moment, only simple data types are supported (no arrays or objects). You can flatten your data before adding where necessary, e.g. instead of "categories": ["Men", "Shirts"] use "category1": "Men", "category2": "Shirts".

Example Files

JSON

[{
    "sku": "3938-691-926",
    "title": "Puke Duke",
    "description": "Das Bier mit Zimt-Vanille-Geschmack.\nInhalt:\n- Eine Dose à 0,5 Liter.",
    "bigImageLink": "https://abload.de/img/puke_dukevxke2.jpg",
    "smallImageLink": "https://abload.de/thumb/puke_dukevxke2.jpg",
    "category": "Getränke → Bier",
    "price": 1.09,
    "currency": "€",
    "stockQuantity": 120
}]

XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <row>
    <sku>3938-691-926</sku>
    <title>Puke Duke</title>
    <description>Das Bier mit Zimt-Vanille-Geschmack.
Inhalt:
- Eine Dose à 0,5 Liter.</description>
    <bigImageLink>https://abload.de/img/puke_dukevxke2.jpg</bigImageLink>
    <smallImageLink>https://abload.de/thumb/puke_dukevxke2.jpg</smallImageLink>
    <category>Getränke → Bier</category>
    <price>1.19</price>
    <currency>€</currency>
    <stockQuantity>120</stockQuantity>
  </row>
</root>

File Location and Folder Structure

• We scan the root folder of your FTP location (specified in your Product feed settings) for new feed files.

• The file will be moved to the /processed folder if

  • it has been successfully processed. If the file itself could be processed but individual products could not be updated this will be reported but we still consider the file processed.

• The file will be moved to the /error folder if

  • we could not read the file (for example because it did not contain a valid JSON or XML structure).

  • we could only partially process a file (for example where the first half of a file contains valid JSON objects but the second half contains a different structure)

  • the timestamp in the file name could not be parses (meaning we found a file with the product_feed_ prefix but could not read the timestamp following the prefix)

• The file will be moved to the /ignored folder if

  • the timestamp in the filename is in the future.

  • multiple files were found (in this case the newest file will be processed while the other files will be ignored)

  • Files in the root folder without the prefix product_feed_ will not be touched by the product feed functionality.

Upload Frequency

File uploads should be used for the initial upload and for infrequently synchronization of the respective product databases. A maximum of one file per day is processed. More frequent updates can be performed using the Product Feed API.

When using the API we still recommend performing a full synchronization by uploading a product feed file in regular intervals. This minimizes the impact of potential networking or system errors occurring during the API usage.

For implementation and testing purposes it is also possible to temporarily increase the feed file processing frequency. Please reach out to your CrossEngage contact to arrange this.

File Processing and Error Handling

Product feed processing can end with four different results:

1. The file was fully processed and we were able to process every product in the file.

2. The file itself was fully processed but we had to skip individual products.

3. The file was partially processed, i.e. we encountered an invalid format after processing a part of the file.

4. The file was not processed at all.

For case 1 we will clean-up all products with a last modification timestamp older than the file timestamp.

For cases 2, 3 and 4 we would not perform any clean-up as there is a risk of unintentionally removing products (which were in a part of the file that could not be processed).

The results will be reported in the Activity Log.

Product Feed Events

The following functionality is disabled by default. Please reach out to your CrossEngage contact to have it enabled. These events can only be used in real-time user journeys and are not available for segmentation.

When a product is updated either through a product feed or through our API, CrossEngage will observe changes in either the stockQuantity field or the price field of each product. If any of these values change, we emit the events listed below. When using these events in the user journeys of real-time campaigns, keep in mind that the journey builder does not validate the journey logic.

When submitting other product-related events such as Added/Removed Product or Added/Removed to Wishlist to CrossEngage, you will need to include the sku of the respective product on the top level of your event payload. This allows you to combine these events with the events generated by CrossEngage in real-time campaign user journeys.

Product Back In Stock

This event is triggered when the stock quantity is not empty and changes from 0 to 1 or more. No event will be triggered in other cases, for example where a product was not available in previous product feeds but becomes available again or where the stock quantity value was not available and becomes available again.

The following event properties are available in user journeys and real-time campaign messages:

Property	Description
sku	The sku of the product
currency	The currency of the product
updatedAt	The timestamp of the product update
title	The product title
previous.stockQuantity	The previous stock quantity
stockQuantity	The current stock quantity
price	The current price of the product

Product Low Stock

This event is triggered when the stock quantity is not empty and changes from 6 or more to 5 or less. The following event properties are available:

Property	Description
sku	The sku of the product
currency	The currency of the product
updatedAt	The timestamp of the product update
title	The product title
previous.stockQuantity	The previous stock quantity
stockQuantity	The current stock quantity
price	The current price of the product

Product Price Increased

This event is triggered when the price for a product is available and increases. Any increase will trigger this event, even if it is just a cent. The following event properties are available:

Property	Description
sku	The sku of the product
currency	The currency of the product
updatedAt	The timestamp of the product update
title	The product title
stockQuantity	The current stock quantity
price	The current price of the product
previous.price	The previous price of the product quantity
percentage.price.difference	The relative price difference
absolute.price.difference	The absolute price difference

Product Price Reduced

This event is triggered when the price for a product is available and decreases. Any decrease will trigger this event, even if it is just a cent. The following event properties are available:

Property	Description
sku	The sku of the product
currency	The currency of the product
updatedAt	The timestamp of the product update
title	The product title
stockQuantity	The current stock quantity
price	The current price of the product
previous.price	The previous price of the product quantity
percentage.price.difference	The relative price difference
absolute.price.difference	The absolute price difference

With each upload, all existing products are updated and new products are added. All products which have not been re-uploaded during the latest import are marked as deleted. They are not completely erased from our database, however they are flagged as inactive. Therefore, if you wish to keep these products active, please make sure you upload them during each import.

Important: Uploading the product feed with several new products will result in deletion of all your existing products. Your product feed will then contain only those new products you imported with the last product feed.