Nobody Preheats Microwaves


    1.2.4 • Public • Published

    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 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


    npm i sphere-category-sync

    DownloadsWeekly Downloads






    Unpacked Size

    89.3 kB

    Total Files


    Last publish


    • chukwuemeka
    • ahmetoz
    • commercetools-admin
    • emmenko
    • hajoeichler
    • yanns
    • tdeekens
    • timonrey
    • vineetkumarkushwaha
    • acbeni
    • markusazer
    • jherey
    • danrleyt
    • jenschude