Import a product catalog into Kameleoon using the Product Recommendation API

The Product Recommendation API is the preferred method for catalog imports exceeding 50,000 products. Use this endpoint instead of daily full catalog re-imports. This tutorial describes the steps and common pitfalls for importing a product catalog into Kameleoon using the Product Recommendation API. The Product Recommendation API follows RESTful principles. The import process involves these consecutive steps:

Import Categories: Send a POST request to ensure all categories are up to date before uploading products.
Import and Update Products: Send a PUT request to import the product catalog into the Kameleoon account.
Update available products : PATCH request to update the availability of Products.

The API also provides an endpoint dedicated to changing the availability of existing products in Kameleoon, which is a more lightweight approach.

Data

Shop ID eehj3eu84299kg5ghw5a6743r8 & Shop Secret pmd5362597thrgq8k256ep01t0
- Locate these in Recommendations > Settings > Store settings in the Kameleoon app. Contact the Customer Success Manager for the key if necessary.

Webhooks http://www.webhook.com/importCategoriesApiResponses/ & http://www.webhook.com/importProductsApiResponses/
- Webhooks ensure completion of the Import Categories step before the catalog import and verify completion of the Import Products request.
Current Product Catalog in Kameleoon:

[
  {
    "id": "PD1",
    "group_id": "Shoe",
    "name": "Sneaker",
    "price": 1,
    "oldprice": 2,
    "currency": "USD",
    "url": "https://example.com/product",
    "picture": "https://example.com/product/image.png",
    "available": true,
    "categories": ["shoesID"],
    "locations": [
      {
        "location": "USA",
        "delivery_types": {
          "store": 10,
          "delivery": 50
        }
      },
      {
        "location": "CAN",
        "price": 60
      }
    ]
  },
  {
    "id": "PD2",
    "group_id": "Glass",
    "name": "Sunglasses",
    "price": 1,
    "oldprice": 2,
    "currency": "USD",
    "url": "https://example.com/product",
    "picture": "https://example.com/product/image.png",
    "available": true,
    "categories": ["glassID"],
    "locations": [
      {
        "location": "USA",
        "delivery_types": {
          "store": 10,
          "delivery": 50
        }
      },
      {
        "location": "CAN",
        "price": 60
      }
    ]
  }
]

Current Categories in Kameleoon:

[
  {
    "id": "glassID",
    "name": "Glass"
  },
  {
    "id": "shoesID",
    "name": "shoes"
  }
]

Products to import in Kameleoon:
- The price of PD2 (Glass) has changed to three and there is a new product with a new category ("id": "bootID", "name": "Boot")

{
  "id": "PD3",
  "group_id": "Boot",
  "name": "Standard Boot",
  "price": 1,
  "oldprice": 2,
  "currency": "USD",
  "url": "https://example.com/product",
  "picture": "https://example.com/product/image.png",
  "available": true,
  "categories": ["bootID"],
  "locations": [
    {
      "location": "USA",
      "delivery_types": {
        "store": 10,
        "delivery": 50
      }
    },
    {
      "location": "CAN",
      "price": 60
    }
  ]
}

Import categories

Use the Import categories endpoint for this step. Send the data as a JSON string within the request body. Send all categories in a single POST request. The following example sends all categories, both existing and new, to enable the import of new products:

curl -X POST -L 'https://api.products.kameleoon.com/import/categories' \
             -H 'Content-Type: application/json' \
             -d '{
   "shop_id":"eehj3eu84299kg5ghw5a6743r8",
   "shop_secret":"pmd5362597thrgq8k256ep01t0",
   "items":[
      {
         "id":"glassID",
         "name":"Glass"
      },
      {
         "id":"shoesID",
         "name":"shoes"
      },
      {
         "id":"bootID",
         "name":"boots"
      }
   ],
   "webhook":"http://www.webhook.com/importCategoriesApiResponses/"
}'

The webhook notifies the developer upon request completion. When Kameleoon imports all specified categories and they become available, it sends a POST request to the designated webhook.Use the webhook for large category imports, as processing may take several minutes.If importing products using the import product endpoint, the webhook ensures Kameleoon processes all categories before beginning the product import. Kameleoon ignores products without a known category during import.Example of a successful request:

{ "status": "success"}

Example of an unsuccessful request:

{ "status": "error",  "message": "MESSAGE"}

Import and update products

Use the Import Products endpoint for this step. The API limit is 40 requests per minute, with a maximum of one request every 1.5 seconds. The request weight limit is 35 megabytes. The following example sends the updated product PD2, with modified price and oldprice fields, and the new product PD3. This example omits product PD1 because it remains unchanged.

# !!! IMPORTANT: Wait for a successful POST request to the webhook endpoint
# (http://www.webhook.com/importCategoriesApiResponses)
# from the Import Categories step before making this call.

#Check that all required fields are filled for each product

curl -X PUT -L 'https://api.products.kameleoon.com/import/products' \
             -H 'Content-Type: application/json' \
             -d '{
   "shop_id":"eehj3eu84299kg5ghw5a6743r8",
   "shop_secret":"pmd5362597thrgq8k256ep01t0",
   "items":[
{
      "id": "PD3",
      "group_id": "Boot",
      "name": "StandardBoot",
      "price": 1,
      "oldprice": 2,
      "currency": "USD",
      "url": "https://example.com/product",
      "picture": "https://example.com/product/image.png",
      "available": true,
      "categories": ["bootID"],
      "locations": [
        {
          "location": "USA",
          "delivery_types": {
            "store": 10,
            "delivery": 50
          }
        },
        {
          "location": "CAN",
          "price": 60
        }
      ]
    },
    {
      "id": "PD2",
      "group_id": "Glass",
      "name": "Sunglasses",
      "price": 3,
      "oldprice": 1,
      "currency": "USD",
      "url": "https://example.com/product",
      "picture": "https://example.com/product/image.png",
      "available": true,
      "categories": ["glassID"],
      "locations": [
        {
          "location": "USA",
          "delivery_types": {
            "store": 10,
            "delivery": 50
          }
        },
        {
          "location": "CAN",
          "price": 60
        }
      ]
    }
   ],
   "webhook":"http://www.webhook.com/importProductsApiResponses/"
}'

# check for the result of the request, which will be sent 
# to the provided webhook http://www.webhook.com/importProductsApiResponses/

Update available products

Use the Update available products endpoint to manage stock status. This endpoint updates the list of available products using their IDs. In this scenario, you mark product PD1 as unavailable by providing IDs for PD2 and PD3 and omitting the ID for PD1.

curl -X PATCH -L 'https://api.products.kameleoon.com/import/products' \
             -H 'Content-Type: application/json' \
             -d '{
   "shop_id":"eehj3eu84299kg5ghw5a6743r8",
   "shop_secret":"pmd5362597thrgq8k256ep01t0",
   "items":["PD2","PD3"]
}'

Key recommendations

Workflow Order
Always import categories before products
Data Completeness
Product imports require all mandatory fields
Webhook Strategy
Essential for monitoring large imports
Performance Tips
- Batch products ≤35 MB
- Rate limit: 40 requests/minute
- Only use the Update available products endpoint to change a product’s availability.
Error Handling
- Verify category IDs
- Check field formats
- Monitor webhook responses

​Data

​Import categories

​Import and update products

​Update available products

​Key recommendations

Data

Import categories

Import and update products

Update available products

Key recommendations