Skip to content

PIM Product Bulk Load API Reference

Bizzkit PIM provides bulk load API endpoints which are designed to import products into PIM and which are optimized for importing large amounts of data.

Purpose and scope

The main purpose of the bulk load API is to provide a way to import large amounts of data. Example use cases of this are:

  • Product data migration from another system to Bizzkit PIM
  • Synchronizing product data in Bizzkit PIM with data from an external system

Currently, the following functionality is supported by the bulk load API:

  • Creation of new products which do not exist in Bizzkit PIM yet
  • Updating existing products
  • Setting/changing the primary category of products (new or existing)
  • Placing products (new or existing) in additional categories

Endpoints

The bulk load API endpoints are JSON based endpoints for importing product data.

Info

Please see PIM Preview API Reference for more details on the actual API endpoints.

Inserting new products

Adding new product data using the bulk load API can be done in two ways:

  • By calling the /api/products/bulk-load endpoint with JSON data directly in the request body
  • By calling the /api/products/bulk-load-from-file endpoint with a JSON file in the request body

These endpoints for inserting new product data assume that the provided products don't exist yet in PIM, which allows for high-performance bulk loading of data.

Updating existing products

The /api/products/bulk-upsert endpoint can be used for updating products already existing in PIM, as well as inserting new products. It has a slight overhead compared to the /api/products/bulk-load and /api/products/bulk-load-from-file endpoints, so for maximum performance regarding importing new products those endpoints should be used instead.

Data schema

The following schema definitions describe the data model which is used to interact with the bulk load API endpoints:

Examples

Here are some simple examples of using the model.

Attribute with a single field and single value

Given a single value attribute called ATTR1 with one field named VALUE of type PString, the following JSON will create a product with a unique name PRODUCT1:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT1",
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR1",
                    "values": [
                        {
                            "VALUE": "Lorem ipsum ..."
                        }
                    ]
                }
            ]
        }
    ]
}

Attribute with a multiple fields and a single value

Given a single value attribute called ATTR2 with a field named VALUE1 of type PString, a field named VALUE2 of type PDateTime, and a field named VALUE2 of type PInt32, the following JSON will create a product with a unique name PRODUCT2:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT2",
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR2",
                    "values": [
                        {
                            "VALUE1": "Lorem ipsum ...",
                            "VALUE2": 42,
                            "VALUE3": "2024-05-30T07:48:00Z"
                        }
                    ]
                }
            ]
        }
    ]
}

Attribute with a single field and segmented value

Given a single value attribute called ATTR3 with a field named VALUE of type PChannelSpecificString, the following JSON will create a product with a unique name PRODUCT3:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT3",
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR3",
                    "values": [
                        {
                            "VALUE": "Default value",
                            "VALUE:Segments": [
                                {
                                    "value": "Value channel 1",
                                    "channel": "CHANNEL1"
                                },
                                {
                                    "value": "Value channel 2",
                                    "channel": "CHANNEL2"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Attribute with a single field and multiple values

Given a multiple value attribute called ATTR4 with one field named VALUE of type PString, the following JSON will create a product with a unique name PRODUCT4:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT4",
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR4",
                    "values": [
                        {
                            "VALUE": "Value1"
                        },
                        {
                            "VALUE": "Value2"
                        },
                        {
                            "VALUE": "Value3"
                        }
                    ]
                }
            ]
        }
    ]
}

Add product to category

Given a single value attribute called ATTR1 with one field named VALUE of type PString, the following JSON will create a product with a unique name PRODUCT5 and add the product to a category called CATEGORY1:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT5",
            "categories": [
                "CATEGORY1"
            ],
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR1",
                    "values": [
                        {
                            "VALUE": "Lorem ipsum ..."
                        }
                    ]
                }
            ]
        }
    ]
}

Attribute with a reference to a global list

Given an attribute called ATTR5 with a reference to a global list called LIST1, the following JSON will create a product with a unique name PRODUCT6 and the ATTR5 attribute with a reference to a item with system name LIST1_K_0 in the global list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT6",    
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR5",
                    "values": [
                        {
                            "VALUE": "LIST1_K_0"
                        }
                    ]
                }
            ]
        }
    ]
}

Please note that you need to reference the key of the item, not the value.