Skip to content

JSON Import API Reference

Bizzkit PIM provides JSON import 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 JSON import 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 JSON import 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

Unique Name is the identifier for the products in the JSON importer.

Limitations

The following is not supported by the JSON import API:

  • Creating attributes, global list items, or other referential data that is normally not set in the product view
  • Partial updates of an attribute value. This both include adding new values to a multi-valued attribute and changing the value of a single field of an attribute. The whole attribute value has to be included
  • Changing master / variant structures
  • Changing the product name
  • Set up bundle

Endpoints

The JSON import API endpoints are JSON based endpoints for importing product data.

Info

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

Inserting new products

Adding new product data can be done by calling the /api/products/import/json/new-products endpoint with a JSON file in the request body. This endpoint 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/import/json 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/import/json/new-products endpoint, so for maximum performance regarding importing new products this endpoint should be used instead.

Data schema

The following schema definitions describe the data model which is used to interact with the JSON import 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"
                        }
                    ]
                }
            ]
        }
    ]
}

For removing values from a multi-valued attribute the same syntax can be used, as the provided array of values overwrites all the current values of the attribute. In order to remove all of the values set in the previous example, the following JSON should be used:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "reference": "Import reference",
    "products": [
        {
            "uniqueName": "PRODUCT4",
            "isPublished": true,
            "attributes": [
                {
                    "systemName": "ATTR4",
                    "values": []
                }
            ]
        }
    ]
}

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 the categories CATEGORY1 (as primary) and CATEGORY2:

 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": "PRODUCT5",
            "categoryPlacements": [
                {
                    "systemName": "CATEGORY1",
                    "isPrimary": true
                },
                {
                    "systemName": "CATEGORY2",
                    "isPrimary": false
                }
            ],
            "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 an 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.

Attribute with an externally owned values

Externally owned values can be set in the same way as PIM owned values, using the externallyOwnedValues property on attributes model.
The following JSON will create an attribute which have an externally owned value.

 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",
                    "externallyOwnedValues": [
                        {
                            "VALUE": "Externally owned Lorem ipsum ..."
                        }
                    ]
                }
            ]
        }
    ]
}

Note that it is possible to set both values and externallyOwnedValues at the same time.

Response from the endpoints

From both /api/products/import/json and /api/products/import/json/new-products endpoints, the response model is the same. The response will contain a model with the following properties:

1
2
3
4
5
{
    "taskId": "guid",
    "statusUri": "string",
    "resultUri": "string"
}

where the statusUri is the URI to the API endpoint to check the status of the import task and the resultUri is the URI to view the result of the import task. An example of a response could be:

1
2
3
4
5
{
    "taskId": "7de91816-19ce-4387-9893-06b310710ee7",
    "statusUri": "/tasks/7de91816-19ce-4387-9893-06b310710ee7/status",
    "resultUri": "/tasks/7de91816-19ce-4387-9893-06b310710ee7/result"
}

Making a request to /api/tasks/{taskId}/status will return the current status of the import task. Here is an example of a response:

1
2
3
4
5
6
7
8
{
    "state": "Finished",
    "progress": 100,
    "lastUpdate": "2025-01-23T12:06:59.5456039+00:00",
    "name": "BulkLoadProductsFromJson",
    "userId": "bdc95ea6-e9ef-4575-96ee-346e8f7f549f",
    "hasInputFile": false
}

Making a request to /api/tasks/{taskId}/result will return the result of the import task. Here is an example of a response:

1
"The specified task has not finished"

If you need to see the input file used for the import task, you can make a request to /api/tasks/{taskId}/input-file.