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 Personalization | Description | Format | Mandatory? |
---|---|---|---|---|
id | Product ID | Unique identifier for each product. The value supports valid Unicode characters. This field is case sensitive. Limit: Up to 50 characters | Example: VS-234HD-Q | Yes |
title | Product name | Provide 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 - 1080p | Yes |
description | Product description | Product 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 pictures | Yes |
image_link | Image url | URL to display the main image of your product. | https://samplewebsite.com/xyz.jpg | Yes |
product_category | Category | The main category of the product. You can specify multiple categories using comma (,). | camera | Yes |
brand | Brand | Brand name (manufacturer) of the product. | CityCool | No |
inventory | Inventory | Total number of products in stock. Provide a numeric value. | 37 | No |
availability | Availability | Product's availability for purchase by customer. Provide value as TRUE or FALSE. | TRUE | No |
price | Price | Product's price with currency. Do not provide 0 in this field | 110.00 USD | No |
sale_price | Sale price | Product's price at which is avaiable for sale, with currency. | 199.00 USD | No |
margin | Margin | Profit margin percentage for the product. This field is essential to create recommendations strategy based on this attribute. | 20 | No |
Notes:
- 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
Note:
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 file | Field name in Personalization | Description | Example | Mandatory? |
---|---|---|---|---|
product_rating | Product rating | Overall rating of product This is a custom attribute. Provide a numeric or decimal value | 4.3 | No |
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 attribute | Corresponding CSV field | Data type | Description | Mandatory? | Value to use if null |
---|---|---|---|---|---|
id doc_id | id | string | Product ID Format for doc_id is null: Ex: if id= A_11, then doc_id will be null:A_11 | Yes | |
title | Title | string | Product title | Yes | |
description | Description | string | Product description | Yes | |
images | Image_link | array | Displays product images. Add multiple image URLs separated by comma | Yes | |
categories | product_category | array | Product category | Yes | |
brand | brand | string | Product manufacturer | No | "" |
custom_number_inventory | inventory | Product inventory | No | 0 | |
custom_boolean_availability | availability | Boolean | Product availability | No | false |
price_value price_currency | price | Product price | No | 0 "" | |
custom_string_sale_price | sale_price | Product price for sale | No | "" | |
custom_number_margin | margin | Profit margin on the product | No | 0 | |
custom_number_product_rating | product_rating | Rating for the product | No | 0 | |
custom_string_custom_field_1 | custom_field_1 | Custom field | No | "" | |
custom_string_custom_field_2 | custom_field_2 | Custom field | No | "" |
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": [
"https://citycoolretail.acoustic-demo.com:7443/wcsstore/ExtendedSitesCatalogAssetStore/images/catalog/cc_main/cc_cameras_files/cc_030.jpg"
],
"categories": [
"cc_cameras",
"cc_electronics"
],
"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"
}
]
}
Updated almost 2 years ago