Skip to main content

Import Categories

If you have an external system like an ERP or PIM that contains a category structure in which you want to organize and display your product catalog, you can import this category structure into Propeller. In this scenario the external system is the single source of truth for the category structure. In this use case you typically use the bulk category REST endpoints by source ID.

Endpoint​

POST /v2/categories/bulk/sourceId

Request body​

{
  "categories": [
    {
      "sourceId": "011000",
      "source": "REST-API",
      "language": "NL",
      "names": [
        { "language": "NL", "value": "Fiets" },
        { "language": "EN", "value": "Bike" }
      ],
      "descriptions": [
        { "language": "NL", "value": "Fiets" },
        { "language": "EN", "value": "Bike" }
      ],
      "shortDescriptions": [
        { "language": "NL", "value": "Fiets" },
        { "language": "EN", "value": "Bike" }
      ],
      "parent": {
        "sourceId": "136045"
      }
    },
    {
      "sourceId": "020000",
      "source": "REST-API",
      "language": "NL",
      "names": [
        { "language": "NL", "value": "Accessoires" },
        { "language": "EN", "value": "Accessories" }
      ],
      "descriptions": [
        { "language": "NL", "value": "Accessoires" },
        { "language": "EN", "value": "Accessories" }
      ],
      "shortDescriptions": [
        { "language": "NL", "value": "Accessoires" },
        { "language": "EN", "value": "Accessories" }
      ],
      "parent": {
        "sourceId": "136045"
      }
    },
    {
      "sourceId": "020100",
      "source": "REST-API",
      "language": "NL",
      "names": [
        { "language": "NL", "value": "GPS" },
        { "language": "EN", "value": "GPS" }
      ],
      "descriptions": [
        { "language": "NL", "value": "GPS" },
        { "language": "EN", "value": "GPS" }
      ],
      "shortDescriptions": [
        { "language": "NL", "value": "GPS" },
        { "language": "EN", "value": "GPS" }
      ],
      "parent": {
        "sourceId": "136045"
      }
    }
  ],
  "directives": [
    {
      "fields": ["names", "descriptions"],
      "operation": "skipIfNotEmpty"
    },
    {
      "fields": [],
      "operation": "skipMoveOnUpdate"
    }
  ]
}

The request includes:

  • categories[] contains the categories to create or update
  • source and sourceId identify each category in the external system
  • parent.sourceId references the parent category to build the tree structure
  • names, descriptions and shortDescriptions accept multiple languages
  • directives[] controls how updates are handled (see Directives below)

Source identification​

The source field should clearly refer to the origin of the category data, for example "MyERP" or "MyPIM". The sourceId is the unique identifier of that category in the source system. This combination allows you to update the category information or structure later using the same endpoint. The bulk category REST endpoint uses upsert operations and will either create new categories or update existing ones. See Sources for more on how source combinations work.

Building the tree​

You build the tree structure by filling the parent.sourceId field on each category with the sourceId of its parent category. Each category gets one parent. Because parents are referenced by sourceId, you can import an entire tree in a single call without needing Propeller internal IDs.

Category fields​

You can fill names, descriptions and shortDescriptions in multiple languages. The hidden field controls whether the category is visible on your frontends. Set it to "Y" for internal or temporary categories that should not be displayed.

Category attributes​

You can send category attributes in the same payload using an attributeDescriptionId and a value. The value format depends on the type of attribute you are filling. See the REST API Reference for the attributes schema.

Directives​

Directives are optional but can be useful when the external system and Propeller each own different parts of the category data.

skipIfNotEmpty: use this when you want the category structure to come from the external system but you want to enrich specific fields in Propeller. Specify the fields you want to protect (for example names and descriptions). On future updates, those fields will not be overwritten if they already have content in Propeller. This way you can manage your structure externally and enrich category names and descriptions in Propeller without the risk of them getting overwritten.

skipMoveOnUpdate: use this when you want category names and field data to come from the external system but you want the freedom to organize the category structure in Propeller. Updates from the source will keep updating fields like names and descriptions, but the tree structure you have created in Propeller will remain unchanged.

See Directives for the full list of available directives.

Response​

Each category in the batch returns a result:

{
  "Success": true,
  "Key": "020000",
  "Id": 1736,
  "Action": "update",
  "lookupKey": "sourceId"
}
  • Success indicates whether the operation succeeded
  • Key is the sourceId of the category
  • Id is the Propeller internal category ID
  • Action is create or update depending on whether the category already existed
  • lookupKey confirms the identifier type used

The overall response includes a Messages field (with value "Completed" on success) and a Total count of processed categories.

See also​