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:
Example:
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: |
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 |
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 ( |
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 |
Example Files
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:
The file was fully processed and we were able to process every product in the file.
The file itself was fully processed but we had to skip individual products.
The file was partially processed, i.e. we encountered an invalid format after processing a part of the file.
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.
Last updated