1. ChannelEngine Help Center
  2. APIs
  3. Channel Management API

Articles in this section

Channel Management API: getting started

  • Created
  • Updated

About this article

This article explains how to set up a Channel Management API integration with ChannelEngine, covering authentication, the configuration sequence, purge-and-replace behavior, rate limits, and what to verify before going live.

Table of contents

Introduction

Two APIs, two keys

Requirements

Available endpoints

Authentication

Response envelope

The setup sequence

Purge-and-replace behavior

Rate limits

Debugging and support

Integration readiness checklist

Common issues

Next steps

Introduction

The Channel Management API is how your channel configures its presence on ChannelEngine before any seller connects. It covers three things: your category tree, your product content attributes, and your offer attributes. Once these are in place, every seller who connects to your channel sees the correct structure for mapping their products and offers.

This is a one-time-use API, not a synchronization layer. You call it when your channel's structure changes - not on a regular schedule. Day-to-day product and order flows happen through the separate Channel API.

This guide covers everything you need to get your Channel Management API integration up and running: authentication, the setup sequence, how the purge-and-replace behavior works, rate limits, and what to check before you go live.

Two APIs, two keys

ChannelEngine provides two distinct APIs for channel integrations. It is important to understand which is which before you start, because they use different API keys and serve completely different purposes.

API Purpose When you use it Resource URL
Channel Management API Configure your channel's structure on ChannelEngine - categories, content attributes, and offer attributes. During initial setup and whenever your channel's structure changes. https://www.channelengine.net/channelmanagement-api/docs
Channel API Day-to-day data exchange - retrieve products and offers, post orders, handle shipments, cancelations, and returns. Continuously, as part of your live integration. https://[tenant].channelengine.net/api
NB: the Channel Management API uses a separate API key from the Channel API. Using a Channel API key on Channel Management API endpoints - or vice versa - results in authentication errors. Keep these keys clearly labeled in every environment.

Requirements

  • Access to the Channel Management API - not enabled by default. Request it from your ChannelEngine implementation contact. Without this, all requests return 403 Forbidden.
  • A Channel Management API key - issued separately from your Channel API key. Find it on ChannelEngine under Settings > API keys once access has been granted.
  • Familiarity with REST APIs and JSON - the API follows standard REST conventions with JSON request and response bodies.
  • A planned channel structure - decide your category hierarchy and which attributes your channel requires before your first call. Changing these later means resending your entire configuration.

The full API reference is available at https://www.channelengine.net/channelmanagement-api/docs. Use it alongside this guide for full field-level detail on each endpoint.

Available endpoints

The Channel Management API covers three areas of channel configuration. Each area has a POST endpoint to send your configuration and a GET endpoint to read back what is currently stored.

Categories

  • Export category tree: POST /v1/categories/list
    Export your full category hierarchy. Every call replaces the entire category tree stored for your channel.
  • Retrieve category tree: GET /v1/categories/list
    Retrieve the category tree currently stored for your channel. Primarily a development tool for verifying a previous POST.

Content attributes

  • Export content attributes: POST /v1/attributes/data
    Export your product content attributes - the fields describing what a product is (title, description, brand, color, material, and so on). Can be scoped to specific categories or applied globally.
  • Retrieve content attributes: GET /v1/attributes/data
    Retrieve the content attributes currently stored for your channel.

Offer attributes

  • Export offer attributes: POST /v1/attributes/offer
    Export your offer attributes - the fields describing the commercial terms of a listing (price, stock, lead time, shipping class, and so on). Always apply globally, never category-scoped.
  • Retrieve offer attributes: GET /v1/attributes/offer
    Retrieve the offer attributes currently stored for your channel.

Authentication

All Channel Management API requests must include your Channel Management API key in the X-CE-KEY request header:

X-CE-KEY: your-channel-management-api-key

There is no other supported authentication method for this API. If your key is missing or incorrect, the API returns 401 Unauthorized. If your channel has not been granted access to the Channel Management API, it returns 403 Forbidden regardless of the key.

NB: always verify you are using the Channel Management API key - not the Channel API key - in every environment. These are distinct key types and are not interchangeable. A common source of authentication failures is carrying a Channel API key over from a Channel API integration.

Response envelope

Every Channel Management API response uses a standard envelope. Always check the Success field in the response body - never rely on the HTTP status code alone. The API can return HTTP 200 with Success: false.

Field Type Description
Success boolean Whether the operation succeeded. Always check this field explicitly.
Message string Human-readable description of the error when Success is false. Read this first when diagnosing failures.
ValidationErrors object Map of field-level validation failures, keyed by field name. Log this in full when diagnosing errors - it shows exactly which fields failed and why.
StatusCode integer HTTP-equivalent status code within the response body.
RequestId string Unique identifier for this API call. Provide this to ChannelEngine Support when reporting an issue.
LogId string Internal log reference used by the ChannelEngine Support team. Provide this alongside RequestId.
ExceptionType string Machine-readable error classification. Populated only when a server-side exception occurs.
Content object Present on GET responses. Contains the data stored for your channel - the structure varies by endpoint.
NB: log both RequestId and LogId from every API call. When you report an issue to ChannelEngine Support, providing both values allows the team to locate your exact request without needing you to reproduce it.

The setup sequence

The three configuration areas have a dependency order. Attributes can reference categories, so categories must exist before you submit category-scoped attributes. Follow this sequence for your initial setup.

NB: if your channel does not use categories, skip Step 1. Content attributes can be applied globally (no CategoryChannelNoList needed) and offer attributes are always global. In that case, you can submit content and offer attributes in either order.

Step 1: export your category tree

Call POST /v1/categories/list with your full category hierarchy. Each category is an object in the Items array, identified by a ChannelNo that you assign. Categories can be nested by setting a ParentChannelNo.

Key things to get right at this stage:

  • ChannelNo must be globally unique across your entire tree - not just within a level. Use your channel's own internal category IDs.
  • Every ParentChannelNo must reference a ChannelNo included in the same request, or one that already exists from a previous call.
  • Set CanContainProducts: true for any category that sellers should be able to assign products to. Intermediate grouping categories can be set to false.

For full field documentation and an example request, see Channel Management API: categories.

Step 2: export content attributes

Call POST /v1/attributes/data with your complete list of product content attribute definitions. These are the fields sellers see in the Content Mappings step when configuring their product export to your channel.

Key things to get right at this stage:

  • Leave CategoryChannelNoList empty for attributes that apply to all products. Populate it only for attributes that are specific to one or more categories - and only after step 1 is complete.
  • Use AttributeType: STANDARD for the vast majority of attributes. Use PRICE only for attributes that feed into ChannelEngine's pricing v2 tool.
  • Only mark attributes as IsRequired: true if your channel genuinely cannot list a product without that field. Overly strict requirements block sellers during onboarding.
  • ChannelNo should be stable. Changing it later is treated as deleting the old attribute and creating a new one - any existing seller mappings for the old attribute are lost.

For full field documentation and an example request, see Channel Management API: content attributes.

Step 3: export offer attributes

Call POST /v1/attributes/offer with your complete list of offer attribute definitions. These are the fields sellers see in the Pricing step when configuring their offer data for your channel.

Offer attributes work the same way as content attributes, with one difference: they are always global. There is no category scoping for offer fields.

For full field documentation and an example request, see Channel Management API: offer attributes.

Step 4: verify on ChannelEngine

After submitting your configuration, verify it from two angles:

  • Use the GET endpoints - call GET /v1/categories/list, GET /v1/attributes/data, and GET /v1/attributes/offer to confirm the stored data matches what you submitted.
  • Check the ChannelEngine UI - open your channel on ChannelEngine. Your category tree appears in the channel's category selector. Content attributes appear in the Content Mappings step and offer attributes in the Pricing step. This is what sellers see when they connect to your channel - checking it here confirms the seller experience is correct.

Purge-and-replace behavior

All three POST endpoints follow the same pattern: every call completely replaces the stored configuration for that area. This applies to categories, content attributes, and offer attributes alike.

NB: always send your complete configuration in every POST call. Any item not included in the request is permanently deleted. There is no partial update or patch - each call describes the desired end state for the entire set.

In practice, this means:

  • To add a new category, resend your full category tree including the new category.
  • To rename an attribute, resend your full attribute list with the updated name.
  • To remove something, resend the full list without it.

Before your first export in any area, call the matching GET endpoint to check whether ChannelEngine has any default configuration stored for your channel. If it does, include those items in your POST payload so they are not lost.

Rate limits

Every Channel Management API endpoint is rate-limited to two requests per 15 minutes, counted separately per endpoint URL. The POST and GET endpoints for the same resource each have their own independent limit.

In production, this should not be a problem. The Channel Management API is designed for infrequent structural changes - not continuous polling or synchronization. If you are hitting rate limits during development, space out your test calls.

On a 429 Too Many Requests response, wait until the 15-minute window has elapsed before retrying. Retrying immediately will continue producing 429 responses.

Debugging and support

Log RequestId and LogId from every API response. When reporting an issue to ChannelEngine Support, provide both values so the team can locate your exact request in their system without needing you to reproduce it.

When a POST returns Success: false, read Message first for a plain-language description, then check ValidationErrors for field-level detail. The most common causes are:

  • A ChannelNo or Name value that exceeds 200 characters.
  • A CategoryChannelNoList entry that references a category ChannelNo that does not exist.
  • An unsupported enum value for Type, ProductType, or AttributeType.
  • An incorrect or missing API key (check for the Channel API key being used instead of the Channel Management API key).

When a GET returns empty results, it usually means no configuration has been submitted for that area yet - not an API error. Confirm by submitting a POST and then calling GET again.

Integration readiness checklist

Run through this checklist before your channel goes live with sellers.

  • Using a Channel Management API key (not a Channel API key) in every environment.
  • API key passed via the X-CE-KEY header on every request.
  • Checking the Success field on every API response - not just the HTTP status code.
  • Logging RequestId and LogId from every response.
  • Category tree submitted and verified via GET /v1/categories/list.
  • All ChannelNo values in the category tree are globally unique.
  • Content attributes submitted and verified via GET /v1/attributes/data.
  • Category-scoped attributes reference ChannelNo values that exist in the submitted category tree.
  • Only genuinely required fields marked as IsRequired: true.
  • Offer attributes submitted and verified via GET /v1/attributes/offer.
  • Configuration verified in the ChannelEngine UI - categories, Content Mappings step, and Pricing step all look correct.
  • Integration builds and sends the complete configuration on every POST - never a partial update.
  • All ChannelNo values are treated as stable identifiers - not changed without a deliberate migration plan.
  • Full setup sequence tested end-to-end in the demo environment before pointing at production.

Common issues

Symptom Likely cause Fix
401 Unauthorized API key is missing or incorrect. Check that X-CE-KEY is present and contains a valid Channel Management API key - not the Channel API key.
403 Forbidden Your channel has not been granted access to the Channel Management API. Contact your ChannelEngine implementation contact to request access.
200 with Success: false A business-logic validation error occurred. The request was received but the content failed validation. Read Message and ValidationErrors. Common causes: invalid ParentChannelNo reference, value too long, or unsupported enum value.
Configuration disappears after a POST. The POST call replaced the stored configuration - any item not included in the request is deleted. Always send your complete configuration in every POST call. Use the GET endpoint first to retrieve what is currently stored, and include those items in your payload.
Category-scoped attributes not appearing for the right category. CategoryChannelNoList contains a value that does not match any ChannelNo in your submitted category tree, or categories have not been exported yet. Submit your category tree first. Then use the exact same ChannelNo values in CategoryChannelNoList.
Attributes not visible on ChannelEngine after a successful POST. The POST succeeded but the wrong step is being checked. Offer attributes appear in the Pricing step, not the Content Mappings step. Check the correct step: content attributes in the Content Mappings step, offer attributes in the Pricing step.
Seller mappings lost after updating an attribute. The ChannelNo of an existing attribute was changed. ChannelEngine treats this as deleting the old attribute and creating a new one - existing seller mappings for the old ChannelNo are not carried over. Keep ChannelNo values stable. Only update Name, Description, or other metadata fields when iterating on your attribute list.
429 Too Many Requests The rate limit of two calls per 15 minutes per endpoint has been exceeded. Wait until the 15-minute window has elapsed before retrying. Space out test calls during development.

Next steps

Detailed documentation for each endpoint area:

Comments

0 comments

Article is closed for comments.