Personalization

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 following table describes the format of the CSV file for product catalog upload.

Field name in CSV file
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.

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:<id>

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 3 months ago



Create your product catalog


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.