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 upload

After creating the product catalog, you need to upload it to Personalization. You have multiple options to choose from, to upload or update the product catalog.

When you update the product catalog file for your organization, then existing products are updated, and new products are added to the existing product catalog.

To avoid discrepancies when attribute columns are added or deleted from the catalog, it is recommended to upload the entire catalog with your updates, and not just the newly added records.

Example: You upload a new product catalog file containing product ids P1, P2, and P3 to Acoustic Personalization. Later, you decide to update the price for P1 and add few more products (P4 and P5) to the existing catalog. So, your new catalog file should have P1 (with the updated price), P2, P3, and P4, P5 (new products). After you upload the new file, product P1 gets updated and products P4 and P5 are added. The records for products P2 and P3 continue to exist with their original values.

Prerequisites

  • The organization and channel for which you want to upload the product catalog must be registered in Acoustic Personalization. In other words, you must have the org ID (for the organization) and the channel tenant ID (for the channel) as registered in Acoustic Personalization.
  • You must have the Authorization key specific to the organization for which you want to upload the product catalog. This Authorization Key is shared separately with each customer. If you do not have this key, contact Acoustic Support.

Using REST API tool

You can upload your product catalog using any of the REST API tools. This topic illustrates the procedure using Postman tool.

Create an instance for your organization

Before uploading the product catalog for the first time, you must create an instance for your organization.

  1. Using a REST API tool (for example, Postman), open this URL:
    https://api-personalization-us-1.goacoustic.com/service/catalog/create-instance/
  2. In the URL, replace with your org ID. For example, if your channel tenant ID is cw-507581967-FTTVdDgB, then the org ID will be 507581967.
  3. Go to the Headers tab.
  4. Add the following header parameters and their values:
Parameter
Value

Accept

application/json

Content-Type

application/json

Authorization

Provide the authorization key. This key is specific to each organization. If you do not have this key, contact Acoustic Support.

  1. Go to the Body tab.
  2. Click raw option. Do not enter any data under this option.
  3. Click Send.
    On successful instance creation, a message code appears "201", which indicates that the instance ID is created.
    For example, if your Response is {"id":"pc-123456789-db8YXrc6"}, then the instance ID is pc-123456789-db8YXrc6.

The following table shows some of the common error codes and their resolutions.

Status code
Description
Issue resolution

400

Invalid org ID

Provide the correct org ID and then retry the instance creation.

  1. Copy the instance ID from the response body.

Important!

Ensure to keep a note of the instance ID; because this ID is required to upload a new product catalog or update an existing catalog for your organization.

Upload new catalog as a CSV file

Perform the following steps to upload a new product catalog in the CSV file format.

  1. Create a .csv file with the fields as described in the topic Product catalog specification.
  2. Add the product catalog data to be uploaded.
  3. Save the CSV file.
  4. Using a REST API tool (for example, Postman), open this URL:
    https://api-personalization-us-1.goacoustic.com/service/catalog/v2/product-feed///upload

  5. In the URL:

    • Replace with your org ID. For example, if your channel tenant ID is cw-507581967-FTTVdDgB, then the org ID will be 507581967.
    • Replace with the instance ID that you created.
  6. Go to the Headers tab.
  7. Add the following header parameters and their values:
Parameter
Value

Accept

application/json

Authorization

Provide the authorization key. This key is specific to each organization. If you do not have this key, contact Acoustic Support.

  1. Go to the Body tab.
  2. Click form-data option.
  3. For the KEY field, manually type the value as file (must be lower-case). Then, from the drop-down list, select the File option.
  1. In the Value field, click Select Files. Navigate and select your product catalog CSV file.
  2. Click Send.
    On successful file upload, a message appears: “File ingested successfully.”

The following table shows some of the common error codes.

Status code
Description
Issue Resolution

400

The [test.txt] file upload failed. The file format is not supported.

Change the file format to .csv and try the upload again.

422

The file name already exists.

Specify a different file name and then try upload again.

You can retry the file upload after fixing these issues.

Update existing catalog as a CSV file

Important

When you update the catalog again for your instance ID, you can either update the existing product catalog CSV file, or you can create another CSV file with the same name.

For example: You uploaded a catalog with name abc.csv for instance ID A. If you want to update the catalog again for instance ID A, you must upload the new CSV file with the same file name abc.csv.
If you upload a CSV file with the different name, the upload fails and following error appears: "The catalog name does not match with the catalog name [testcatalog.csv] that is already uploaded for your instance ID."

Examples
You upload a new product catalog [catalog1.csv] file containing product ids P1, P2, and P3 to Acoustic Personalization. Later, you decide to update the price for P1 and add few more products to the existing catalog. You create another CSV file with the same name [catalog1.csv] containing the records for the product ids P1, P5, and P6. After you upload the file, product P1 gets updated, and products P5, P6 are added. The records for products P2 and P3 continue to exist in Acoustic Personalization and are not deleted.
You upload a new product catalog [catalog1.csv] file containing product id P1 and having attributes A1, A2, and A3. Later, you decide to update the value for A1 and add two more attributes A4 and A5 to the existing product P1. You can either edit the current CSV file or create another CSV file with the same name [catalog1.csv], containing the records for the product P1 and attributes A1, A4, and A5. After you upload the file, the attribute A1 gets updated, and the new attributes A4, A5 are added.

Procedure

  1. Update the product catalog data, either in the existing CSV file, or in a different CSV file with the same name.
  2. Save the CSV file.
  3. Using a REST API tool (for example, Postman), open this URL:
    https://api-personalization-us-1.goacoustic.com/service/catalog/v2/product-feed///upload

  4. In the URL:

    • Replace with your org ID. For example, if your channel tenant ID is cw-507581967-FTTVdDgB, then the org ID will be 507581967.
    • Replace with the instance ID that you created.
  5. Go to the Headers tab.
  6. Add the following header parameters and their values:
Parameter
Value

Accept

application/json

Authorization

Provide the authorization key.
This key is specific to each organization. If you do not have this key, contact Acoustic Support.

  1. Go to the Body tab.
  2. Click form-data option.
  3. For the KEY field, manually type the value as file (must be lower-case). Then, from the drop-down list, select the File option.
  4. Click Choose Files. Navigate and select your product catalog CSV file.
  5. Click Send.
    On successful file upload, a message appears: “File ingested successfully.”
    The following table shows some of the common error codes.
Status Code
Description
Issue Resolution

400

The [test.txt] file upload failed. The file format is not supported.

Change the file format to .csv and try the upload again.

406

The catalog name does not match with catalog name [testcatalog]
that is already uploaded for your instance ID.

Provide the correct catalog name, and then try the upload again.

You can retry the file upload after fixing these issues.

Update catalog using JSON data

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.

Perform these steps to update your product catalog as JSON data.

  1. Create a JSON with the fields as described in the topic Product catalog specification.
  2. Add the product catalog data to be updated.
  3. Save the JSON.
  4. Using any REST API tool (such as Postman), open this URL:
    https://api-personalization-us-1.goacoustic.com/service/catalog///ingest-json
  5. In the URL:

  6. Go to Headers tab and provide the following header parameters and their values.

Parameter
Value

Accept

application/json

Content-Type

application/json

Authorization

Provide the authorization key. This authorization key is specific to each organization. If you do not have this key, contact Acoustic Support.

  1. Next, go to the Body tab.
  2. Click the raw option.
  3. In the text field, paste the contents of your product catalog JSON data.
  4. Click Send.
    On successful JSON data upload, a message code appears: 201 which indicates that the JSON has been ingested successfully.

The following table shows some of the common error codes.

Status code
Description
Issue Resolution

500

Document was not ingested

You can retry the JSON upload after fixing issues in the JSON data.

Upload new catalog using curl

You can also upload or update your product catalog using curl command.
Using curl command gives you the flexibility to perform product catalog upload unattended, without the need for human involvement. Also, you can choose to schedule the catalog upload by using the curl command in combination with a scheduling mechanism of your choice.

The syntax for the curl command is as follows:

curl --location --request POST 'https://api-personalization-us-1.goacoustic.com/service/catalog/v2/product-feed///upload' \
--header 'Accept: multipart/form-data' 
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: ' \
--form 'file=''/.csv'

In the command, make the following changes:

  • Replace with your org ID.
  • Replace with the instance ID.
  • Replace with the authorization key. This authorization key is specific to each organization. If you do not have this key, contact Acoustic Support.
  • Replace with the directory location of the product catalog CSV file.
  • Replace with the name of the product catalog CSV file.

Here is an example:

curl --location --request POST 'https://api-personalization-us-1.goacoustic.com/service/catalog/v2/product-feed/123456789/pc-123456789-abcde007/upload' \
--header 'Accept: multipart/form-data' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: abcd1234efgh56789' \
--form 'file='/ProductCatalog/upload'/PZN-catalog-pc-123456789-abcde007.csv'

After you run the curl command, the product catalog CSV is picked up and converted internally into JSON data.

Update catalog using curl

If you want to update an existing product catalog, specify the same org ID, instance ID, and the CSV file name as the original product catalog.
For example, if your original product catalog file is testcatalog.csv, then to update the catalog, provide the same file name (testcatalog.csv) as well as the same org ID and the instance ID.

CSV file names are treated as case-insensitive. This means that testcatalog.csv and TESTCATALOG.csv are considered as the same file.

One Org may have multiple instances, and each instance is associated with a catalog. For example, consider that an Org ClientOrg has two instances: instanceid1 (associated with catalog1.csv), and instanceid2 (catalog2.csv).
If you try to update catalog2.csv by specifying instanceid1, an error message informs that the catalog file already exists in the Org.
Hence, you must specify the correct instance ID when updating the product catalog.

Upload new catalog using SFTP

You can upload a new catalog or update an existing catalog using Secure File Transfer Protocol (SFTP). Perform the following steps.

  1. Ensure that the catalog files are in the CSV format and meet the product catalog specifications.
  2. Create a ticket with Acoustic Support for the credentials required to access the SFTP location. Provide the org ID and channel ID for which you want to upload the catalog files.
  3. Acoustic Support will provide you with the following details:
    • Host name
    • Port number
    • Username
    • SSH Private Key
  4. Use an SFTP client of your choice (for example, WinSCP, FileZilla, and so on) to upload the catalog files.

Next steps

After you've uploaded the product catalog, you can now proceed with creating a product recommendations strategy.

Updated 24 days ago


Product catalog upload


Suggested Edits are limited on API Reference Pages

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