Importing a Product Catalog into Kameleoon using the Product Recommendation API

The Product Recommendation API is the preferred method to import your catalog if you have more than 50,000 products. We also strongly recommend using this endpoint rather than fully re-importing your catalog daily.

This tutorial will guide you through the different steps and the common pitfalls on how to import a Product Catalog into Kameleoon using the Product Recommendation API.

Our Product Recommendation API is a RESTful API.

Here are the consecutive steps :

Import Categories: POST request to ensure that all categories are up to date before uploading products
Import and Update Products: PUT request to Import your Product Catalog into your Kameleoon account.
Update available products : PATCH request to update the availability of Products.

note

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
- These can be found in Recommendations > Settings > Store settings in the Kameleoon app. You can also contact your Customer Success Manager for the key.

webhooks http://www.webhook.com/importCategoriesApiResponses/ & http://www.webhook.com/importProductsApiResponses/
- Webhooks are essential for ensuring the completion of the Import Categories step before you import your product catalog, and for verifying the completion of the Import Products request.
Current Product Catalog in Kameleoon:

[
{
    "id": "PD1", // String (max 64). Required
    "group_id": "Shoe", // String (max 64). Optional
    "name": "Sneaker", // String (max 255). Required
    "price": "1", // Float (positive). Required
    "oldprice": "2", // Float (positive). Optional
    "currency": "USD", // Currency code: USD, EUR. Required.
    "url": "https://example.com/product", // String (URL). Required
    "picture": "https://example.com/product/image.png", // String (URL). Required
    "available": true, // Boolean (true, false). Required
    "categories": ["shoeID"], // Array of categories IDs. Required.
    "locations": [ 
    {
        "location": "USA",
        "delivery_types": {
            "store": 10,
            "stock": 50  }
    },
    {
        "location": "CAN",
        "price": 60
    }
    ]
},
{
    "id": "PD2", // String (max 64). Required
    "group_id": "Glass", // String (max 64). Optional
    "name": "Sunglasses", // String (max 255). Required
    "price": "1", // Float (positive). Required
    "oldprice": "2", // Float (positive). Optional
    "currency": "USD", // Currency code: USD, EUR. Required.
    "url": "https://example.com/product", // String (URL). Required
    "picture": "https://example.com/product/image.png", // String (URL). Required
    "available": true, // Boolean (true, false). Required
    "categories": ["glassID"], // Array of categories IDs. Required.
    "locations": [ 
    {
        "location": "USA",
        "delivery_types": {
            "store": 10,
            "stock": 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", // String (max 64). Required
    "group_id": "Boot", // String (max 64). Optional
    "name": "Standard Boot", // String (max 255). Required
    "price": "1", // Float (positive). Required
    "oldprice": "2", // Float (positive). Optional
    "currency": "USD", // Currency code: USD, EUR. Required.
    "url": "https://example.com/product", // String (URL). Required
    "picture": "https://example.com/product/image.png", // String (URL). Required
    "available": true, // Boolean (true, false). Required
    "categories": ["bootID"], // Array of categories IDs. Required.
    "locations": [ 
    {
        "location": "USA",
        "delivery_types": {
            "store": 10,
            "stock": 50  }
    },
    {
        "location": "CAN",
        "price": 60
    }
    ]
}

Import Categories

We will be using the Import categories endpoint for this step.

info

Before uploading products, you must upload an up-to-date list of categories into our database.

Data is sent as a JSON string that includes the body of the request. You must send all categories in a single request as it is a POST request.

Here, we sent all categories—both existing and newly created—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":"slassID",
         "name":"Glass"
      },
      {
         "id":"shoesID",
         "name":"shoes"
      },
      {
         "id":"bootID",
         "name":"boots"
      }
   ],
   "webhook":"http://www.webhook.com/importCategoriesApiResponses/"
}'

note

The webhook serves to notify the developer once a request has been completed. When all specified categories in the API call have been imported and are fully available, a POST request will be sent to the designated webhook.

We highly recommend using the webhook if you are importing a large number of categories, as processing them in Kameleoon may take several minutes.

If you are importing products using our import product endpoint, using the webhook ensures that all categories have been fully processed before initiating the product import. Since categories must be processed by Kameleoon first, any products without a known category will be ignored during the import process.

Example of a successful request:

{ "status": "success"}

Example of an unsuccessful request:

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

Import and Update Products

We will be using the Import Products endpoint for this step. The API has a request limit of 40 requests per minute with a maximum of 1 request every 1.5 seconds. And its request weigh limit is capped at 35 megabytes per request.

info

If you want to update only certain products, you must provide all mandatory parameter values for each product in the request. If any product's mandatory properties are omitted, the product will be ignored during the import, and no changes will be made in our database. For example, if you want to update a product's price, you must include all its mandatory parameters, such as category, name, picture, and tags.

For non-mandatory properties, any omitted values will result in those properties being removed from our database.

You can check the mandatory fields in the endpoint documentation.

Here, we sent the modified product, PD2, with the fields price and oldprice modified, and the additional product, PD3. You don't have to send PD1, as it remains the same.

# !!! IMPORTANT you should wait until a successful POST request has been sent to the webhook endpoint of the 
# Import Categories step (http://www.webhook.com/importCategoriesApiResponses)
# 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", // String (max 64). Required
    "group_id": "Boot", // String (max 64). Optional
    "name": "StandardBoot", // String (max 255). Required
    "price": "1", // Float (positive). Required
    "oldprice": "2", // Float (positive). Optional
    "currency": "USD", // Currency code: USD, EUR. Required.
    "url": "https://example.com/product", // String (URL). Required
    "picture": "https://example.com/product/image.png", // String (URL). Required
    "available": true, // Boolean (true, false). Required
    "categories": ["bootID"], // Array of categories IDs. Required.
    "locations": [ 
    {
        "location": "USA",
        "delivery_types": {
            "store": 10,
            "stock": 50  }
    },
    {
        "location": "CAN",
        "price": 60
    }
    ]
},
{
    "id": "PD2", // String (max 64). Required
    "group_id": "Glass", // String (max 64). Optional
    "name": "Sunglasses", // String (max 255). Required
    "price": "3", // Float (positive). Required
    "oldprice": "1", // Float (positive). Optional
    "currency": "USD", // Currency code: USD, EUR. Required.
    "url": "https://example.com/product", // String (URL). Required
    "picture": "https://example.com/product/image.png", // String (URL). Required
    "available": true, // Boolean (true, false). Required
    "categories": ["glassID"], // Array of categories IDs. Required.
    "locations": [ 
    {
        "location": "USA",
        "delivery_types": {
            "store": 10,
            "stock": 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

We will be using the Update available products endpoint.

Use this endpoint to update the list of products that are available (in-stock) using a list of IDs of all available items.

For our use case, we just imported products into Kameleoon (see steps above), and we want to make the product PD1 unavailable. To do so, we provide the product ID of available products (PD2, PD3) and omit the ID of unavailable products (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 ≤35MB
- 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