Channel Management API: categories

About this article

This article explains how to submit your channel's full category hierarchy to ChannelEngine using POST /v1/categories/list, and how to verify the result during development with GET /v1/categories/list.

Table of contents

Introduction

Overview

Before you start

Requirements

How categories work

• Choosing a ChannelNo
• Timing and frequency

Available API endpoints

• Submit hierarchy POST /v1/categories/list
• Verify submitted hierarchy GET /v1/categories/list

Testing

Common issues

Next steps

Introduction

If your marketplace organises products into a category tree, ChannelEngine needs to know that structure before sellers can map their products to it. The Channel Management API lets your channel export its full category hierarchy in one call — a single export that applies to every seller connected to your channel, not something you repeat per merchant. Every call replaces your entire category tree, so updating even one category means resending the full hierarchy.

Overview

Refer to the flowchart below to visualise how a category hierarchy is submitted to ChannelEngine and made visible to all sellers on your channel.

Before you start

Keep the following in mind before making your first call:

• Sending purge-and-replace, not incremental. Every POST call overwrites your entire category tree. Anything you do not include gets deleted. Always send your complete hierarchy, not just what changed.
• One call reaches every seller at once. There's no per-merchant submission — a single call updates the tree for everyone on your channel simultaneously.
• Call it rarely, and at night. This is a heavy operation. Run it during off-peak hours, and only when your hierarchy has actually changed — not on a routine schedule.
• ChannelNo must be your internal ID, and globally unique. It is the value returned to you via the Channel API, so use your own system's category ID — and make sure it is unique across your entire tree, not just per level.

Requirements

• Access to the Channel Management API — granted by ChannelEngine. Contact your implementation specialist or ChannelEngine Support if you do not have this yet.
• Channel API key — pass it in the X-CE-KEY request header. Find it in your ChannelEngine environment under Settings → API keys.
• A planned category structure — decide how categories relate to one another as parents and children before your first POST call. Submitting the full tree in one pass — parents and children together — is simpler than building it up across many small updates.

How categories work

Every category is identified by a ChannelNo — a unique reference you assign yourself. Categories can be nested by setting ParentChannelNo to the ChannelNo of another category, building up a tree of any depth. Top-level categories have no parent.

The CanContainProducts field tells ChannelEngine whether sellers are allowed to assign products directly to that category, or whether it exists purely to group other categories together.

Choosing a ChannelNo

The ChannelNo that you assign here is not only used within the Channel Management API — it is also the value your integration receives back when retrieving category data through the Channel API, for example on a product's CategoryTrail or category reference fields. ChannelEngine shares this exact ChannelNo with your channel so it can be processed easily on your side.

Set ChannelNo to your own internal category ID — the identifier your systems already use to recognise that category — rather than a display name or a value generated just for this call. That way, when the same ChannelNo comes back through the Channel API, your integration can match it directly to the right category in your own systems without an extra lookup or mapping step.

Timing and frequency

Replacing your full category tree is a heavy operation for ChannelEngine to process — the entire hierarchy is recomputed and made visible to every seller on your channel at once. Keep the following in mind:

• Schedule it at night. Run POST /v1/categories/list during low-traffic, off-peak hours rather than during the day, to minimise impact on the platform.
• Call it as rarely as possible. Restrict calls to at most once a day — preferably much less often, such as once a week or only when your hierarchy actually changes. There is no benefit to resending an unchanged tree.
• You send a single export to all sellers. You never need to repeat the call per merchant — one call updates the tree for every seller connected to your channel at once.

Because POST /v1/categories/list purges and replaces the entire tree, consider giving sellers a heads-up before you send the update — for example, through your own seller communications or release notes. A category change can affect products that are already mapped to your categories, so sellers benefit from knowing in advance that the structure is about to change.

Available API endpoints

There are two category endpoints in the Channel Management API:

• Submit category hierarchy: POST /v1/categories/list
  Send your full category hierarchy to ChannelEngine. Each call describes the desired end state for your entire tree.
• Retrieve category hierarchy: GET /v1/categories/list
  Read back the category tree currently stored for your channel. Primarily a development tool for confirming a POST call was applied correctly.

Submit hierarchy POST /v1/categories/list

• Submit category hierarchy: POST /v1/categories/list

Use this endpoint to create or update your category tree in ChannelEngine. Each call submits the full list of categories you want stored — think of it as describing the desired end state rather than appending individual categories one at a time.

Making the request

Send a POST request with a JSON body, authenticating with your Channel API key in the request header:

POST https://www.channelengine.net/channelmanagement-api/v1/categories/list
X-CE-KEY: YOUR_API_KEY
Content-Type: application/json

A practical example using cURL:

curl -X POST \
  "https://www.channelengine.net/channelmanagement-api/v1/categories/list" \
  -H "X-CE-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Items": [
      {
        "ChannelNo": "ELEC",
        "ParentChannelNo": null,
        "Name": "Electronics",
        "CanContainProducts": false
      },
      {
        "ChannelNo": "ELEC-AUDIO-HEAD",
        "ParentChannelNo": "ELEC",
        "Name": "Headphones",
        "CanContainProducts": true
      }
    ]
  }'

In this example, Electronics is a top-level grouping category that cannot hold products directly. Headphones sits beneath it and is where sellers actually assign products. When submitting a parent category and its children in the same call, the order of items in the array does not matter — ChannelEngine resolves the parent-child relationships from ChannelNo and ParentChannelNo regardless of the order they appear in.

Request body fields

The request body contains a single Items array. Each entry describes one category.

Response

A successful submission returns HTTP 200 with Success: true in the response body:

{
  "StatusCode": 200,
  "RequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "LogId": "log-998877",
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": {}
}

Verify submitted hierarchy GET /v1/categories/list

• Retrieve category hierarchy: GET /v1/categories/list

Use this endpoint to read back the category tree currently stored for your channel, exactly as ChannelEngine has it. Because POST /v1/categories/list doesn't return your data back to you in its response, GET is how you verify what was actually saved. This is primarily a development tool — useful for confirming that a POST call was applied correctly while you're building your integration.

Making the request

Send a GET request, authenticating with your Channel API key in the request header. The endpoint takes no parameters:

GET https://www.channelengine.net/channelmanagement-api/v1/categories/list
X-CE-KEY: YOUR_API_KEY

A practical example using cURL:

curl -X GET \
  "https://www.channelengine.net/channelmanagement-api/v1/categories/list" \
  -H "X-CE-KEY: YOUR_API_KEY"

Response structure

A successful call returns HTTP 200 with your full category tree in a single response — there's no pagination to handle, since category trees are typically small compared to product or order data:

{
  "Content": {
    "Items": [
      {
        "ChannelNo": "ELEC",
        "ParentChannelNo": null,
        "Name": "Electronics",
        "CanContainProducts": false
      },
      {
        "ChannelNo": "ELEC-AUDIO-HEAD",
        "ParentChannelNo": "ELEC",
        "Name": "Headphones",
        "CanContainProducts": true
      }
    ]
  },
  "StatusCode": 200,
  "RequestId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "LogId": "log-998878",
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": {}
}

The category data sits in Content.Items and uses the same field shape as the POST request body — see How categories work above for field descriptions.

Envelope fields

Testing

Use the ChannelEngine demo environment to test your category integration end-to-end before pointing it at a production tenant.

1. Plan your category tree. Sketch out the full hierarchy you want to submit, including which categories are top-level and which are nested under a parent.
2. Submit your category tree. Call POST /v1/categories/list with your full Items array. Confirm the response returns Success: true. If Success is false, check ValidationErrors before retrying.
3. Verify with GET. Call GET /v1/categories/list and confirm every category you submitted appears with the correct Name, ParentChannelNo, and CanContainProducts values.
4. Test an update. Submit one of the same ChannelNo values again with a changed Name, then call GET again to confirm the update was applied rather than creating a duplicate.
5. Confirm the purge-and-replace behaviour. Call POST /v1/categories/list again, this time omitting one of the categories you previously submitted. Call GET afterwards and confirm the omitted category is now gone. This confirms your integration always builds and sends the complete category tree — never a partial update — before you rely on this in production.
6. Test error cases. Intentionally submit a category with a ParentChannelNo that doesn't exist. Confirm the response returns a meaningful Message or ValidationErrors entry with Success: false. Validating your error-handling logic here prevents silent failures in production.

Common issues

Next steps

After your category tree is in place, connect these endpoints:

• POST /v1/attributes/data — another Channel Management API endpoint, used to export your product field attributes (separate from categories). You can optionally restrict attributes to specific categories you've already created.
• GET /v2/products/data — retrieve product content, including the category each product has been mapped to.

Use RequestId and LogId from any response when contacting ChannelEngine Support about a specific API call.