Product API example

Description

If online store does not contain group products, then on the product card pages, you need to call the product API code retailrocket.products.post({}) and pass all information about the product in it.

If the integration requires support for group products, you need to call the product API code retailrocket.productsGroup.post({}).

Important: If the website contains the functionality of a quick view window, then the tracking code must be called when a window opens.

Example of code without grouped products

<script type="text/javascript">
    (window["rrApiOnReady"] = window["rrApiOnReady"] || []).push(function() {
        retailrocket.products.post({
            "id": <product ID>,
            "name": "Example product name",
            "price": 777,
            "pictureUrl": "http://example.com/path/to/Photo.jpg",
            "url": "http://www.example.com/path/to/productPage",
            "isAvailable": true,
            "categoryPaths": ["Women/Clothes/Skirts","Women/New Arrivals"],
            "description": "Some text description",
            "vendor": "Brand name",
            "model": "Model name",
            "typePrefix": "Product type",
            "oldPrice": 999,
            "params": {
                    "<custom parameter 1 name>":  "<custom parameter 1 value>",
                    "<custom parameter 2 name>":  "<custom parameter 2 value>",
                    "<custom parameter N name>":  "<custom parameter N value>"
               }
        });
        rrApi.view(<product ID>);
    });
</script>

Example of code with grouped products

<script type="text/javascript">
    (window["rrApiOnReady"] = window["rrApiOnReady"] || []).push(function() {
        retailrocket.productsGroup.post({
            "groupId": <group ID>,
            "name": "<string>",
            "price": 777,
            "pictureUrl": "http://example.com/path/to/Photo.jpg",
            "url": "http://www.example.com/path/to/productPage",
            "isAvailable": true,			
            "categoryPaths": ["Example/Category/Path","Another/Category"],
            "description": "Some text description",
            "products": {
"<product id>": {
                       "isAvailable": <bool>,
                       "name": "<string>",
                       "color": "<string>",
                       "size": "<string>",
                       "url": "<string>",
                       "pictureUrl": "<string>",
                       "price": <decimal>,
                       "oldPrice": <decimal>,
                       "description": "<string>",
                       "params": {
                           "<custom parameter 1 name>": "<custom parameter 1 value>",
                           "<custom parameter 2 name>": "<custom parameter 2 value>",
                           "<custom parameter N name>": "<custom parameter N value>"
                       }	
                },
"<product id>": {
                       "isAvailable": <bool>,
                       "name": "<string>",
                       "color": "<string>",
                       "size": "<string>",
                       "url": "<string>",
                       "pictureUrl": "<string>",
                       "price": <decimal>,
                       "oldPrice": <decimal>,
                       "description": "<string>",
                       "params": {
                           "<custom parameter 1 name>": "<custom parameter 1 value>",
                           "<custom parameter 2 name>": "<custom parameter 2 value>",
                           "<custom parameter N name>": "<custom parameter N value>"
                       }	
                }
            },
            "vendor": "Brand name",
            "model": "Model name",
            "typePrefix": "Product type",
            "oldPrice": 999		
        });

        rrApi.groupView([<product IDs>]);
    });
</script>

Required Product API parameters without grouped products support

Parameter	Description
id	The unique identifier for the product. This attribute can only contain numbers. The maximum identifier length is 16 characters. The id value must not exceed 9 007 199 254 740 991.
name	Product name (maximum 120 characters). We recommend you use the full, unique product name as the product name.
price	The price per unit of products, cannot be equal to zero.
url	Absolute link to the product page. The maximum length of a URL is 512 characters.
pictureUrl	An absolute link to the product offer image. Format should be jpeg, gif or png. To ensure proper image processing, the recommended size is 400x400 pixels or less than 1MB. The maximum length of a URL is 512 characters.
isAvailable	Product Availability parameter: true - Offer in stock. The store is ready to arrange the delivery / purchase of the product. false - Product offer is missing and/or unavailable. Please note that this parameter is case sensitive. true and True** are different values. It is correct to specify the value of the parameter with a small letter.
categoryPaths	An array consisting of paths to product categories. A slash is used as a separator between categories. The path to the category should accurately reflect the site's menu structure and category nesting (only static category names should be used, it's best not to use URL paths, sidebar filters, or dynamic breadcrumbs). You need to pass paths only to the lowest level categories: if the product is in the categories "Women/Clothes/Skirts" and "Women/Clothes", you need to pass only one path - "Women/Clothes/Skirts". If the product is in several categories, then you need to pass them through a comma, for example ["Women/Clothes/Skirts", "Women/Clothes/Velor"].
description	Description of a product. The description could contain html code. In order to use html you should "wrap" description in CDATA. Note, that description should not exceed 200 characters. This parameter is mandatory. You can pass an empty string as a value if you have no product information to fill this parameter with.

Required Product API parameters with grouped products support

Parameter	Type	Description
products	JSON object	This parameter must contain all products of the group declared as separate objects. The only mandatory parameter for a product is isAvailable. By default, other parameters, such as name/URL/image, will be pulled from the general group parameter declaration.
groupId	integer / string	Identifier of a products group. Combines all offers that are variations of the same product. It should have the same value. If the product is not a group offer, then the identifier of the product offer must be passed to the parameter.

Additional parameters

Parameter	Type	Description
vendor	string	Products vendor (brand) name. Used to generate recommendations by manufacturer (popular by vendor).
oldPrice	number	Old price of a product, no spaces, the fractional part is indicated by a dot, cannot be equal to zero.
params	JSON object	This parameter is intended to determine the properties of the product. Each parameter is described using a separate element in the params object. Params can have only 40 elements included in it. The element is defined as "`<param name>`" : "`<value>`" , where: `<param name>` - parameter name. `<value>` - parameter value, may contain an object. The values passed in the params element can be used for additional filtering of product results. Additional parameters are involved in the formation of recommendations and they can be displayed as additional information in the product card.

Parameter

Type

Description

vendor

string

Products vendor (brand) name. Used to generate recommendations by manufacturer (popular by vendor).

oldPrice

number

Old price of a product, no spaces, the fractional part is indicated by a dot, cannot be equal to zero.

params

JSON object

This parameter is intended to determine the properties of the product. Each parameter is described using a separate element in the params object.
Params can have only 40 elements included in it.
The element is defined as "<param name>" : "<value>" , where:

<param name> - parameter name. <value> - parameter value, may contain an object.

The values passed in the params element can be used for additional filtering of product results.
Additional parameters are involved in the formation of recommendations and they can be displayed as additional information in the product card.

Parameter to support regionality

Parameter	Type	Description
stockId	string	Region, warehouse or language identifier of the user to handle multiple warehouses (that may have different prices and availability for different regions) or countries (in case of different languages, currencies, etc.). Every region / stockId must have at least 5 times more unique visitors per month, than the number of products in this region / stockId. For example, if there are 10000 products in the region, the website must have at least 50000 monthly unique visitors from there.

Multilingual and multicurrency support

If a website contains different languages/currencies, then using additional parameters, you can implement support for the same functionality in Retail Rocket products.

<script type="text/javascript">
    (window["rrApiOnReady"] = window["rrApiOnReady"] || []).push(function() {
        retailrocket.products.post({
            "id": <product ID>,
            "name": "Example product name",
            "price": 777,
            "pictureUrl": "http://example.com/path/to/Photo.jpg",
            "url": "http://www.example.com/path/to/productPage",
            "isAvailable": true,
            "categoryPaths": ["Women/Clothes/Skirts","Women/New Arrivals"],
            "description": "Some text description",
            "vendor": "Brand name",
            "model": "Model name",
            "typePrefix": "Product type",
            "oldPrice": 999,
            "params": {
                    "<custom parameter 1 name>": "<custom parameter 1 value>",
                    "<custom parameter 2 name>": "<custom parameter 2 value>",
                    "<custom parameter N name>": "<custom parameter N value>",
                    "languages": {
                      "<language1>": {
                        "description": "description in language1",
                        "name": "name in language1",
                        "url": "url to product in specific language",
                        "<custom parameter 1 name in language1>": "<custom parameter 1 value>",
                        "<custom parameter 2 name in language1>": "<custom parameter 2 value>",
                        "<custom parameter N name in language1>": "<custom parameter N value>"
                      },
                      "<language2>": {
                        "description": "description in language2",
                        "name": "name in language2",
                        "url": "url to product in specific language",
                        "<custom parameter 1 name in language2>": "<custom parameter 1 value>",
                        "<custom parameter 2 name in language2>": "<custom parameter 2 value>",
                        "<custom parameter N name in language2>": "<custom parameter N value>"
                      }
                    },
                    "currencies": {
                      "EUR": <price in EUR>,
                      "USD": <price in USD>
                    }
                }

        });
    });
</script>