The Acoustic Personalization Developer Hub

Welcome to the Acoustic Personalization developer hub. You'll find comprehensive guides and documentation to help you start working with Acoustic Personalization as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Product catalog specification

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.
There are two ways to submit your product catalog:

  • As a CSV file
  • As JSON data

You can use the CSV file to add new (custom) attributes to your product catalog, or to update the values of existing attributes in the catalog. You can use JSON data to only update the values of existing attributes.
For successful generation of recommendations, ensure to provide the values for all the Mandatory fields. You can use the non-mandatory fields to pass additional product information and to filter the recommendations returned by the models in a more effective manner.

This topic describes the formats for CSV and JSON.

CSV file specification

By default, the CSV file uses comma (,) as the delimiter for the fields. Alternatively, you can also use the Pipe symbol (|) as the delimiter. Irrespective of whether you use comma or pipe symbol as the delimiter for the fields, you must save the file with .csv extension.

To add multiple values within the fields that support multiple values (such as product_category field), only use comma as the separator. If you're using comma as a separator for values within a field, then you must use pipe as the delimiter between two fields.

The following table describes the format of 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. 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 availabiity 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 if you want to create Product recommendations strategy based on this attribute.

20

No

Notes:

  • If a field with datatype as Integer (for example - margin, inventory, product_rating) is empty, then by default its value is set to 0.
  • 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 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

Adding custom attributes

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

In the case of 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 already existing attributes. The following table describes the format of JSON to be used for product catalog update.

If you do not want to provide value(s) for one or more non-mandatory attributes, it is recommended that you use the value specified in the Value to use if null column. This helps in maintaining a consistent JSON structure, even if one or more non-mandatory attributes are null. For example, if you do not have a value for the field custom_number_inventory then as mentioned in the table below, you should pass the standard value 0. Similarly, if you do not have a value for the field custom_boolean_availability, then you should 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 about a month ago



Product catalog specification


Suggested Edits are limited on API Reference Pages

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