Upload product catalog

After you create the product catalog, upload it to Personalization. You can upload the catalog using a REST API tool such as Postman, cURL command, or SFTP.
You must upload the catalog every time you add attributes or update the values of attributes. You can update the JSON data when you only want to update the values of the attributes.
When you use the cURL command, you have the flexibility to perform the upload unattended. You can also use a scheduling mechanism to set up a schedule for the upload. When you update the catalog, the existing products are updated, and new products are added.

Example: You upload a new product catalog containing product ids P1, P2, and P3. Later, you decide to update the price for P1 and add few more products (P4 and P5) to the existing catalog. So, your updated 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.

📘

Note:

When you add or delete attribute columns, upload the entire catalog. You can cause discrepancies if you update only the added records.

Before you begin:

• Register your organization and channel in Personalization. The org ID and the channel tenant ID are required to upload the catalog.
• You must have the Authorization key specific to your organization. This Authorization Key is shared separately with each customer. If you do not have this key, contact Acoustic support.

Upload using REST API tool

You can upload your product catalog using any REST API tools; here, Postman is used as an example.

Create an instance for your organization
When you upload the catalog for the first time, 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/ORGID
2. In the URL, replace ORGID with your org ID. If your channel tenant ID is cw-507581967-FTTVdDgB, then the org ID will be 507581967.
3. Go to the Headers tab and add the following header parameters and their values:

5. Go to the Body tab and click the raw option. Do not enter any data under this option.
6. Click Send. When the instance is created, a "201" message code indicates that the instance ID is created. If your response is {"id":"pc-123456789-db8YXrc6"}, then the instance ID is pc-123456789-db8YXrc6.
   On successful instance creation, a message code appears "201", which indicates that the instance ID is created.

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

7. Copy the instance ID from the response body.

📘

Important!

Save the instance ID. You need the ID to upload a new product catalog or update an existing catalog for your organization.

Upload new catalog as a CSV

After you create an instance for your organization, upload the product catalog. You need to upload it in the CSV file format when you upload it for the first time.

1. Create a .csv file with the required fields. For more information, see the Create your product catalog.
2. Add the product catalog data to be uploaded.
3. Save the CSV file with UTF-8 encoding.
4. Using a REST API tool, open this URL: https://api-personalization-us-1.goacoustic.com/service/catalog/v2/product-feed/ORGID/INSTANCEID/upload
5. In the URL:

• Replace ORGID with your org ID. If your channel tenant ID is cw-507581967-FTTVdDgB, then the org ID will be 507581967.
• Replace INSTANCEID with the instance ID that you created.

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

7. Go to the Body tab and click form-data option.
8. For the KEY field, type the value as file (must be lower-case).
9. Then, from the drop-down list, select the File option.

10. In the Value field, click Select Files.
11. Navigate and select your product catalog CSV file and click Send.
12. On successful file upload, a message appears: "File ingested successfully."

The following table shows some of the common error codes.

You can retry the file upload after fixing these issues.

Update existing catalog as a CSV file

📘

Important

To update the catalog, either update the existing CSV file or create another CSV file with the same name.

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

Examples 1. You upload a new product catalog [catalog1.csv] file containing product IDs P1, P2, and P3. 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] with 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 Personalization and are not deleted. 2. You upload a new product catalog [catalog1.csv] file containing product ID P1 with 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]. After you upload the file, attribute A1 gets updated, and the new attributes A4, A5 are added.

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, open this URL:
   https://api-personalization-us-1.goacoustic.com/service/catalog/v2/product-feed/ORGID/INSTANCEID/upload
4. In the URL:

• Replace <<OrgID>> with your org ID. For example, if your channel tenant ID is cw-507581967-FTTVdDgB, then the org ID will be 507581967.
• Replace <<InstanceID>> with the instance ID that you created.

5. Go to the Headers tab and add the following header parameters and their values: 

6. Go to the Body tab and click form-data option.
7. For the KEY field, type the value as file (must be lower-case).
8. Then, from the drop-down list, select the File option and click Choose Files.
9. Navigate and select your product catalog CSV file and click Send.
10. On successful file upload, a message appears: "File ingested successfully."
    The following table shows some of the common error codes.

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 required fields. For more information, see Product catalog specification.
2. Add the product catalog data to be updated.
3. Save the JSON.
4. Using any REST API tool, open this URL:
   https://api-personalization-us-1.goacoustic.com/service/catalog/ORGID/INSTANCEID/ingest-json
5. In the URL:

• Replace <<OrgID>> with your org ID. For example: If your channel tenant ID cw-507581967-FTTVdDgB, then the org ID will be 507581967.
• Replace <<InstanceID>> with the instance ID that you created. For example: https://api-personalization-us-1.goacoustic.com/service/catalog/504986625/ pc-123456789-db8YXrc/ingest-json

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

7. Next, go to the  Body tab and click the raw option.
8. In the text field, paste the contents of your product catalog JSON data and click Send.
9. On successful JSON data upload, a message code 201 indicates that the JSON has been ingested.

The following table shows some of the common error codes.

Upload new catalog using cURL

You can also upload or update your product catalog using the cURL command. When you use the cURL command, you have the flexibility to perform the upload unattended. You can also use a scheduling mechanism to set up a schedule for the upload.

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/<<ORGID>>/<<INSTANCEID>>/upload' \
--header 'Accept: multipart/form-data' 
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: <<AUTHORIZATIONKEY>>' \
--form 'file='<<FilePath>>'/<<FILENAME>>.csv'

In the command, make the following changes:

• Replace <<OrgID>> with your org ID.
• Replace <<InstanceID>> with the instance ID.
• Replace <<AuthorizationKey>> with the authorization key. This authorization key is specific to each organization. If you do not have this key, contact Acoustic support.
• Replace <<FilePath>> with the directory location of the product catalog CSV file.
• Replace <<FileName>> 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 into JSON data.

Update catalog using curl
To update a product catalog, specify the org ID, instance ID, and the CSV file name as the original catalog. For example, to update your catalog file testcatalog.csv, provide the same file name (testcatalog.csv), org ID, and instance ID.

📘

Note:

CSV file names are treated as case-insensitive. For example, 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 specify instanceid1 to update catalog2.csv, the following error message is shown: "the catalog file already exists in the org" error. 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 SFTP.  

1. The catalog files must be in CSV format and meet the Create your product catalog.
2. Contact 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:

• Hostname
• Port number
• Username
• SSH Private Key

4. Use an SFTP client of your choice (for example, WinSCP, FileZilla) to upload the catalog files.

You can now proceed with creating a product recommendations strategy.