Import and export a category tree to and from a commercetools project.

Usage no npm install needed!

<script type="module">
  import sphereCategorySync from 'https://cdn.skypack.dev/sphere-category-sync';


commercetools logo

Category sync

Build Status Coverage Status Dependency Status devDependency Status

This component allows you to manage the category tree of your commercetools project by importing, updating and exporting categories via CSV files.


In general the command uses sub-commands for the different tasks.

Base options are:

Usage: bin/category-sync <command> [options]

  export    Export categories
  import    Import categories

  -p, --project-key     project key         [required]
  -i, --client-id       client id
  -s, --client-secret   client secret
  --language            Language used for slugs when referencing parent.
                                                                 [default: "en"]
  --parentBy            Property used to reference parent - use externalId or
                        slug or id                       [default: "externalId"]
  --continueOnProblems  Continue with creating/updating further categories even
                        if API returned with 400 status code.
                                                      [boolean] [default: false]
  -h, --help            Show help
  --verbose             Add more information regarding the current run
  --debug               Add information to debug
  --version             Show version number

The tool uses the API to talk to SPHERE.IO and therefore needs the 3 access properties - project key, client id and client secret. For automation reason you may use our project credentials files to avoid passing the credentials via command line options.

When you provide a wrong argument or one argument is missing the tool will inform you. Please have a look at the last line of the output. You might find some useful hints like this one:

Missing required arguments: p


The command line to import or update categories is shown below:

Usage: bin/category-sync -p <project-key> import -f <CSV file>

  -f, --file            CSV file name                          [required]
  --sort true/false     Sort CSV file before importing  [boolean] [default: true]

  bin/category-sync -p my-project-42          Import categories from
  import -f categories.csv                    "categories.csv" file into SPHERE
                                              project with key "my-project-42".

During import we match categories to existing categories according to the externalId. If a category with the same externalId is found we will call it an update as the tool will then update the existing category properties - like name etc. - to those values defined in the CSV file. If no matching category is found the tool will create a new one. The import sub-command will never delete a category.

When importing categories, the right order has to be provided to ensure that the category parent already exists before importing a category. For this purpose you can specify a --sort parameter which will preprocess categories and sort them before importing.

Importing custom fields

This tool can import also category custom fields. First, the CTP API type with custom field definitions has to be created. Example type can look like this.

After the type has been created, categories with custom fields can be imported:


More detailed example of CSV with various custom fields can be found here.


To export categories, you can pass a CSV file as template. The template needs to contain only the header. This will allow you to define the content of the output file to your specific needs. Please have a look at the CSV Format section for the different headers supported. If no template is provided using the `-t' parameter, all possible category attributes will be exported incl. all localisations.

The command line to export categories into a CSV file is:

Usage: bin/category-sync -p <project-key> [options] export -t <CSV file> -o <CSV file>

  -t, --template  CSV template file name
  -o, --output    CSV output file name                                [required]

  bin/category-sync -p my-project-42          Export categories from SPHERE
  export -t header.csv -o output.csv          project with key "my-project-42"
                                              into "output.csv" file using the
                                              template "header.csv".

  bin/category-sync -p the-project-1          Export categories from SPHERE
  export -o my.csv                            project with key "the-project-1"
                                              into "my.csv".

Resolving parent category

A category without a parent is called root category. All other categories have a parent. To define a parent by default you provide the externalId of the parent category.

root123,Root Category,
sub123,Sub Category,root123

But you may also use the slug to reference your parent category.

Root Category,root-cat,
Sub Category,sub-cat,root-cat

Ensure that you have set the right language to choose the slug. By default it's English.

CSV Format

In general the CSV is built up of a header row and the content rows. We support the following headers:

Further you might use the following header during export:

  • id: id of category in SPHERE.IO
  • createdAt: The UTC time stamp when the category was created.
  • lastModifiedAt: The UTC time stamp when the category was changed the last time.

Please find some examples in the data folder or in the acceptance tests of the tool in the *.feature located here.

Please note that there is no order in the header.

JSON Format

We support importing categories from JSON file. The import file should be in compliance with the following schema:

  "categories": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "externalId": {
          "type": "string"
        "name": {
          "$ref": "/ltext"
        "slug": {
          "$ref": "/ltext"
        "description": {
          "$ref": "/ltext"
        "orderHint": {
          "type": "string"
        "parent": {
          "$ref": "/reference"
      "required": ["name", "slug"]

For importing JSON file, please use the cli Expected configuration options are:

  • language: (en / de) localization language
  • parentBy: (externalId, slug)

A sample cli command is as follows:

./bin/sphere import -p my-project-key -t category -f testCategories.json -c '{"language":"de", "parentBy":"externalId"}'

Localized attributes

Different languages for the same attribute are defined by a suffix to the actual header delimited by a . - examples are name.de or slug.en. You may define as many languages as you want for those attributes.

Custom fields

This module can also export custom fields from category object. When given the following template, exporter will store custom.type.key in a customType column and customField.* columns will be filled with corresponding custom fields.



categoryKey,categorySlugEn,customTypeKey,123,9876 EUR

More advanced CSV template for exporting custom fields can be found here.


If you just want to use the tool, we recommend to use SPHERE.IO's impex platform to avoid any local installation - you only need your browser.

Nevertheless, running the program locally, you need NodeJS installed and simply run the following command in your terminal:

npm install sphere-category-sync

You may also install it globally if you have sufficent rights on your computer:

npm install -g sphere-category-sync


  • Clone this repository and change into the directory

  • Install all necessary dependencies with

    npm install
  • Convert CoffeeScript into JavaScript by

    npm run build
  • To run the test do:

    npm test
  • To run the tests on each change you do to any *.coffee file run

    npm run watch:test