Create your product catalog

In order to display the recommendations on your channel, you must provide the product information such as product ID, price, inventory, and so on, in the form of product catalog. The catalog should be created and uploaded to Acoustic Personalization before you create a recommendation.

You can upload your product catalog either as a CSV file or as JSON data. Use the CSV file in the following scenarios:

  • To upload a product catalog for the first time.
  • To add new (custom) attributes to your product catalog.
  • To update the values of existing attributes in the catalog.

Use the JSON data in the following scenarios:

  • To update the values of existing attributes.
  • To add new data for the existing attributes. 

To successfully generate recommendations, you must provide the values for all mandatory fields. You can use the non-mandatory fields to pass more product information. You can also filter the recommendations returned by the models effectively.

CSV file specification

By default, the CSV file uses comma (,) as the delimiter for the fields. You can also use the Pipe symbol (|) as the delimiter. You must save the file with the .csv extension.

Use commas to separate values when you add multiple values in a field. If you're using a comma to separate values, then you must use pipe as the delimiter between two fields.

The CSV file should contain headers respective to the catalog data and follow the same delimiter as used for catalog data. The required headers are mentioned in the table below.

The following table describes the format of the CSV file for product catalog upload.

Field name in CSV file (headers)Field name in PersonalizationDescriptionFormatMandatory?
idProduct IDUnique identifier for each product. The value supports valid Unicode characters.
This field is case sensitive.

Limit: Up to 50 characters
Example: VS-234HD-QYes
titleProduct nameProvide the product name that matches the title of the product on your website. This field is case insensitive.

Limit: Up to 150 characters
Example: DC1080 Digital camera - SLR - 20.5 MP - 1080pYes
descriptionProduct descriptionProduct description as shown on your website.
This field is case insensitive.
Limit: Up to 5000 characters
MicroPixel technology with a 18-55 mm lens for high definition picturesYes
image_linkImage urlURL to display the main image of your product.
product_categoryCategoryThe main category of the product. You can specify multiple categories using comma (,).cameraYes
brandBrandBrand name (manufacturer) of the product.CityCoolNo
inventoryInventoryTotal number of products in stock. Provide a numeric value.37No
availabilityAvailabilityProduct's availability for purchase by customer. Provide value as TRUE or FALSE.TRUENo
pricePriceProduct's price with currency. Do not provide 0 in this field110.00 USDNo
sale_priceSale priceProduct's price at which is avaiable for sale, with currency.199.00 USDNo
marginMarginProfit margin percentage for the product. This field is essential to create recommendations strategy based on this attribute.20No


  • If a field with data type as an integer is empty, then by default, its value is set to 0. For example, margin, inventory, product_rating fields.
  • If a field with datatype as String (for example - Description) is empty, then by default, its value is set to "". All the custom attributes have datatype as String.  
  • If a field with datatype as Boolean is empty, then by default, its value is set to False (availability).
  • If the price value is empty, then it is not included in the attribute list. For consistency, it is recommended to use ISO 4217 currency code standard, "X CUR" where X is the numerical value and CUR is the 3-byte currency code. For example, 100.00 USD 



After creating the CSV file with your product catalog data, save it with the UTF-8 encoding.

Adding custom attributes
To add new attributes to the product catalog, you must use CSV file upload. To update the values of existing attributes, you can use either CSV file or JSON data.

For custom attributes, the Name field can have spaces or multiple underscore characters. For example, Product color OR Product_color or Product_color_shade are all valid inputs. All the custom attributes must have datatype as String.

Here is an example of a custom attribute.

Field name in CSV fileField name in PersonalizationDescriptionExampleMandatory?
product_ratingProduct ratingOverall rating of product
This is a custom attribute. Provide a numeric or decimal value

JSON data specification

You can update the product catalog as a JSON to modify the values of existing attributes. The following table describes the format of JSON to be used for product catalog update. If you do want to provide values for non-mandatory attributes, do not leave them empty. Instead, specify the value recommended in the Value to use if null column in the following table. Providing value helps to maintain a consistent JSON structure. For example,

  • If the field custom_number_inventory value is null, then pass the standard value 0.
  • If the field custom_boolean_availability value is null, then pass the standard value false.
JSON attributeCorresponding CSV fieldData typeDescriptionMandatory?Value to use if null
idstringProduct ID

Format for doc_id is null:

Ex: if id= A_11, then doc_id will be null:A_11
titleTitlestringProduct titleYes
descriptionDescriptionstringProduct descriptionYes
imagesImage_linkarrayDisplays product images. Add multiple image URLs separated by commaYes
categoriesproduct_categoryarrayProduct categoryYes
brandbrandstringProduct manufacturerNo""
custom_number_inventoryinventoryProduct inventoryNo0
custom_boolean_availabilityavailabilityBooleanProduct availabilityNofalse
priceProduct priceNo0
custom_string_sale_pricesale_priceProduct price for saleNo""
custom_number_marginmarginProfit margin on the productNo0
custom_number_product_ratingproduct_ratingRating for the productNo0
custom_string_custom_field_1custom_field_1Custom fieldNo""
custom_string_custom_field_2custom_field_2Custom fieldNo""

Example JSON
The following snippet shows a flat sample JSON data for product catalog.

    "documents": [{
            "id": "cc_030",
            "doc_id": "null:cc_030",
            "title": "City Adventure Micropixels Technology Camera",
            "description": "The City Adventurer red camera with MicroPixel technology is   the professional camera with a 18-55 mm lens",
            "images": [
            "categories": [
            "brand": "Canon",
            "custom_number_inventory": 2,
            "custom_boolean_availability": true,
            "price_currency": "USD",
            "price_value": 450.99,
            "custom_number_margin": 314.993,
            "custom_string_vendor_id": "101"