Import a Catalog Tree

Push your ERP category structure into Propeller using the REST API. By the end of this page you will have a category tree with a root category and subcategories.

Prerequisites

• REST API credentials (client_id and client_secret)
• An access token (Authenticate)

Create a root category

Use POST /categories/ to create a single category. The sourceId and source fields let you map the category to its identifier in your ERP.

curl -X POST https://api.helice.cloud/v2/categories/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "EN",
    "names": [
      {"language": "EN", "value": "Industrial Valves"}
    ],
    "parent": {"id": 1},
    "sourceId": "CAT-100",
    "source": "ERP"
  }'

The parent field with {"id": 1} places the category at the top level of the catalog tree. The response returns the new category with its Propeller id.

{
  "data": {
    "id": 1771,
    "names": [{"language": "EN", "value": "Industrial Valves"}],
    "parent": {"id": 1},
    "sourceId": "CAT-100",
    "source": "ERP"
  },
  "messages": ["Category created"]
}

Add subcategories

Create subcategories by referencing the parent category in the parent field.

curl -X POST https://api.helice.cloud/v2/categories/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "EN",
    "names": [
      {"language": "EN", "value": "Ball Valves"}
    ],
    "parent": {"id": 1771},
    "sourceId": "CAT-110",
    "source": "ERP"
  }'

Repeat for each subcategory. For example, create "Gate Valves" with sourceId: "CAT-120" under the same parent.

Import a full tree with the bulk endpoint

For ERP sync the bulk endpoint is more practical. POST /categories/bulk/sourceId creates or updates categories identified by sourceId and source. If a category with the given sourceId already exists it updates the record. If not it creates a new one.

The key advantage is that the parent field references other categories by sourceId instead of Propeller ID. This means you can send the full tree in one request without knowing any Propeller IDs.

curl -X POST https://api.helice.cloud/v2/categories/bulk/sourceId \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [
      {
        "sourceId": "CAT-100",
        "source": "ERP",
        "language": "EN",
        "names": [
          {"language": "EN", "value": "Industrial Valves"}
        ],
        "parent": {"sourceId": "1"}
      },
      {
        "sourceId": "CAT-110",
        "source": "ERP",
        "language": "EN",
        "names": [
          {"language": "EN", "value": "Ball Valves"}
        ],
        "parent": {"sourceId": "CAT-100"}
      },
      {
        "sourceId": "CAT-120",
        "source": "ERP",
        "language": "EN",
        "names": [
          {"language": "EN", "value": "Gate Valves"}
        ],
        "parent": {"sourceId": "CAT-100"}
      }
    ]
  }'

The subcategories reference their parent by sourceId ("parent": {"sourceId": "CAT-100"}), so no Propeller IDs are needed. Running this request again with updated names will update the existing categories instead of creating duplicates.

Directives

The bulk endpoint supports directives to control update behavior:

• skipIfNotEmpty preserves fields that already have a value, useful when the Backoffice team has manually edited category names or descriptions
• skipMoveOnUpdate prevents moving a category to a different parent on update

See the Bulk Categories endpoint for the full directives documentation.

What's next

Continue to Search orders to learn how to export orders for ERP processing.