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

[{
    "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
}]

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.

Last updated