Import and update products

Import or update your product catalog in Kameleoon using the preferred endpoint for catalogs with more than 50K products.

PUT /endpoint

Import and update products

cURL

curl --request PUT \
  --url https://api.example.com/endpoint

import requests

url = "https://api.example.com/endpoint"

response = requests.put(url)

print(response.text)

const options = {method: 'PUT'};

fetch('https://api.example.com/endpoint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/endpoint",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/endpoint"

	req, _ := http.NewRequest("PUT", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.example.com/endpoint")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/endpoint")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body

This endpoint imports your products into your Kameleoon account. It is the preferred method for importing your catalog if you have more than 50K products.

We strongly recommend using this endpoint to also update the list of products and their properties, rather than fully re-importing your catalog daily.

If you rely entirely on this endpoint to import your catalog, ensure that all categories have been imported first using the import categories endpoint. Any products without a known category will be ignored during the import process.

The data is sent as a JSON string in the body of the request.

Rate limit

• The API request limit (Rate Limit) is set at 40 requests per minute, with a maximum of 1 request every 1.5 seconds.
• The API request weight limit (Weight Limit) is capped at 35 megabytes per request.

HTTP Request

PUT https://api.products.kameleoon.com/import/products

List of query parameters

Parameter	Type	Required	Description
shop_id	String	Yes	Your Store Key. You can find this in Recommendations > Settings > Store settings in the Kameleoon app. You can also contact your Customer Success Manager for the key.
shop_secret	String	Yes	Your Secret Key. You can find this in Recommendations > Settings > Store settings in the Kameleoon app. You can also contact your Customer Success Manager for the key.
items	List	Yes	A list of product items. Find in this table the parameters required for items
webhook	String	No	The Webhook URL is where a POST request will be sent upon completion of the import.

The purpose of the webhook is to notify the developer once a request has been completed. Once all products in the API call have been imported and are fully available, a POST request will be sent to the designated webhook.

Example of a successful request:

{
	"status": "success"
}

Example of an unsuccessful request:

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

List of parameters for items object

If you want to update only certain products, you must provide all mandatory parameter values for each product in the request. If any mandatory properties of a product 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 only the price of a product, you must include all its mandatory parameters, such as category, name, picture, tags, etc.

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

Parameter	Type	Required	Description
id	String (max length 64)	Yes	A unique ID assigned to the item
group_id	String (max length 64)	Optional	The ID associated to the item group
name	String (max length 255)	Yes	The name of the item
price	Float (must be positive)	Yes	The price of the item. To provide prices in multiple locations, use the locations object instead.
oldprice	Float (must be positive)	Optional	The previous price of the item
currency	String	Yes	The currency in which the price field was specified
url	String	Yes	A URL to associate with the item
picture	String	Yes	A URL containing an image of the item
available	Boolean	Yes	Indicates whether the item is available for purchase. Use the update products endpoint to update this later
categories	Array of strings	Yes	Each string represents a category ID that this product belongs to.
locations	Array	Optional	Array of prices of the item in different locations. Find in this table the parameters required for locations
accessories	Array of strings	Optional	Contains the product IDs of related accessories for the item
seasonality	Array of integers	Optional	Represents the months of the year (January=1, December=12) that you want to promote this item
brand	String	Optional	The brand name of the item
barcode	Integer	Optional	A barcode value for the item
price_margin	Integer	Optional	The price margin for the item
tags	Array of strings	Optional	A list of keywords that you want to associate with the item
is_child	Boolean	Optional	Indicates whether this item is a child of another item
is_fashion	Boolean	Optional	Indicates whether this item is a fashion item
is_new	Boolean	Optional	Indicates whether this item is a new item
fashion	Object	Optional	Defines several additional parameters for fashion items. Find in this table the parameters required for fashion
stock_quantity	Integer	Optional	The quanity of the item in stock
type_prefix	String	Optional	A prefix to distinguish the type of item
model	String	Optional	The model name of the item
params	Object	Optional	Add custom parameters. Find in this table the parameters required for params
merchant	String	Optional	The merchant you want to associate with the item
rating	Integer	Optional	A value between 1 and 5. The user rating you want to assign to the item
leftovers	String	Optional	A description of the remaining stock.For example, “one” represents a product available as a single unit, “few” represents product in limited quantities (up to 10 units), and “lot” represents a product available in quantities of 10 or more units
creation_date	String	Optional	Must be in the format yyyy-mm-dd. This is the date the item was created

List of parameters for locations object

Use the locations object to provide price, inventory, and other location-specific information when you have multiple locations. Pass the locations object inside the product items object.

Parameter	Type	Required	Description
location	String	Yes	The location you want to specify a price for. This field is required if the locations field is provided.
price	Float (must be positive)	Optional	The price at this location.
oldprice	Float (must be positive)	Optional	The previous price of the item (for example, the regular price of a sale item).
stock_quantity	Int (must be positive)	Optional	The quantity of the item in stock.
sizes	Array of Strings	Optional	A list of size options for the item.
weight	Int (must be positive)	Optional	The weight of the item.
delivery_types	Object	Optional	Indicates the availability of the item. Find in this table the parameters required for delivery_types

List of parameters for delivery_types object

Parameter	Type	Required	Description
store	Int (must be positive)	Yes	Number of items available in-store
delivery	Int (must be positive)	Yes	Number of items available for delivery
delivery	Int (must be positive)	Yes	Number of items available in the warehouse

List of parameters for Params object

The params object allows you to specify custom parameter values for the item. Pass the params object inside the product items object.

Parameter	Type	Required	Description
name	String	Yes	The name of the parameter
value	Array of Strings	Yes	Array of values for the parameter
unit	String	Optional	Unit of measurement for the values.

List of parameters for Fashion object

The fashion object allows you to specify additional information about fashion items. Pass the fashion object inside the product items object.

Parameter	Type	Required	Description
gender	String	Optional	A gender to associate with the item. For example, “m”, “f”, or “female”.
sizes	Array of Strings	Optional	List of sizes for the item.
type	String	Yes	The type of fashion item. For example, “jacket”.

Example JSON request

{
    "id": "myID", // String (max 64). Required
    "group_id": "myGroup", // String (max 64). Optional
    "name": "myItem", // 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": ["ID1", "ID2", ...], // Array of categories IDs. Required.
    "locations": [ 
    {
        "location": "USA",
        "delivery_types": {
            "store": 10,
            "stock": 50  }
    },
    {
        "location": "CAN",
        "price": 60
    }
    ], // Array of prices in locations. See below. Optional
    "accessories": ["ID", "ID", ...], // Array of product IDs. Optional
    "seasonality": [1, 2, ...], // Array of integers (months: 1-12). Optional
    "brand": "...", // String. Optional
    "barcode": "...", // String. Optional
    "price_margin": "...",// Integer. Optional
    "tags": ["TAG1", "TAG2", ...], // Array of strings. Optional
    "is_child": false, // Boolean (true, false). Optional
    "is_fashion": true, // Boolean (true, false). Optional
    "is_new": false, // Boolean (true, false). Optional
    "fashion": {
        "gender": "m",
        "sizes": ["48", "50", "52"],
        "type": "jacket"
    }, // Object. See below. Optional
    "stock_quantity": 60, // Int (positive). Optional
    "type_prefix": "...", // String. Optional
    "model": "Widget 3000", // String. Optional
    "params": [ 
    {
        "name": "Param 1",
        "value": ["bluetooth", "wi-fi"]
    }, 
    {
        "name": "Param 2",
        "value": [23]
    }
    ], // Array of params data. See below. Optional
    "merchant": "...", // String. Optional
    "rating": 4, // Integer (1-5). Optional
    "leftovers": "one", // String (one, few, lot). Optional
    "creation_date": "...", // String. Optional. Format yyyy-mm-dd,
}