Product-Feed

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 Spotler ActivatePro product database (if the record in the Spotler ActivatePro database is older than your file).
• Products not in your file will be removed from the Spotler ActivatePro database (if the record in the Spotler ActivatePro database is older than your file).
• All products in the Spotler ActivatePro database which have an update timestamp newer than the file will be kept and not updated.

In this article you will read about:

• Naming Convention
• File Structure
  • Properties
  • Example Files
• File Location and Folder Structure
• Upload Frequency
• File Processing and Error Handling

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 Spotler ActivatePro 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 Spotler ActivatePro database. The only mandatory field is sku (stock keeping unit) which is the main product identifier in Spotler ActivatePro. 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	Data Type
sku	String	The stock keeping unit of a product (required)
bussinessUnit	String	Business unit a product belongs to
id	String	Identifiers other than SKU which you would like to pass on to Spotler ActivatePro can be submitted through this field. This is a simple text field cannot be used as a Spotler ActivatePro 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, Spotler ActivatePro 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 Spotler ActivatePro 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.