Channel Management API: content attributes

About this article

This article explains how to export and retrieve product content attribute definitions via the Channel Management API, using POST /v1/attributes/data and GET /v1/attributes/data.

Table of contents

Introduction

Overview

Requirements

How attributes work on ChannelEngine

• Content mappings vs. Pricing
• Validation and the product flow
• Global attributes vs. category-specific attributes

Available API endpoints

• POST /v1/attributes/data
• GET /v1/attributes/data

Testing your export

Common issues

Next steps

Introduction

The /v1/attributes/data endpoints are specifically for product content attributes - the fields that describe what a product is, such as title, description, brand, colour, material, or category-specific fields like number of seating places or lens strength. These are distinct from offer attributes (price, stock, shipping), which are managed separately via /v1/attributes/offer.

If your channel requires merchants to map their product content to a specific set of fields, you export those attribute definitions here so that every seller connected to your channel sees them on ChannelEngine and can map their product data accordingly. Once mapped, these values populate the MappedFields of products returned by the Channel API.

Overview

Refer to the diagram below to visualise how attribute definitions flow between your channel, ChannelEngine, and connected merchants.

Requirements

• Access to the Channel Management API - not enabled by default. Request it from your ChannelEngine implementation contact.
• A Channel Management API key - separate from your Channel API key.
• Your category hierarchy is already exported - if any attributes are category-specific, submit your categories first via POST /v1/categories/list so you have the correct ChannelNo values to reference in CategoryChannelNoList.

How attributes work on ChannelEngine

The Channel Management API works at the channel level - not per merchant. When you export your attribute list, a single call makes those attributes visible to every seller connected to your channel at once. Each seller can then map their own product fields to your attributes inside ChannelEngine.

Attributes can apply globally across your entire catalogue, or be scoped to specific categories you have previously exported via POST /v1/categories/list. Once a seller has completed their mapping, the values flow through to MappedFields in products retrieved via the Channel API.

Content mappings vs. Pricing

Every attribute you define ends up in one of two steps inside the seller's ChannelEngine interface, determined by the AttributeType field:

• STANDARD - the attribute appears in the Content mappings step, where sellers map their product fields to your channel's attributes. This is the correct type for the vast majority of attributes: product title, description, brand, color, material, EAN, and so on.
• PRICE - the attribute is moved to the Pricing step, where sellers can use ChannelEngine's pricing tool (pricing v2). Use this only for attributes that are directly related to pricing logic, such as a recommended retail price field or a minimum advertised price. If you are not using pricing v2, set all attributes to STANDARD.

Once you have submitted your attributes, you can verify them directly on ChannelEngine without calling the GET endpoint. Open the channel on ChannelEngine, go to the Mappings, Content mappings. Your exported product content attributes are listed there, showing their names, types, and whether they are required.

Validation and the product flow

Before a product is sent to your channel, ChannelEngine performs a preliminary validation check against the attributes you have marked as required. The outcome of this check determines whether the product reaches you:

• All required attributes have a value - the product passes validation and is included in the response of GET /v2/products/data, ready for your channel to consume.
• One or more required attributes are missing a value - the product does not reach your channel. The seller sees a validation message on ChannelEngine indicating which fields still need to be completed.

Only mark an attribute as IsRequired: true if your channel genuinely cannot process a listing without it. Being too aggressive with required fields prevents sellers from getting any products live until everything is perfectly filled in, which creates friction during onboarding.

Global attributes vs. category-specific attributes

Not every attribute is relevant for every product. Some fields make sense across your entire catalogue; others only apply to specific categories. The CategoryChannelNoList field controls this scope:

• Leave CategoryChannelNoList empty - the attribute is global and applies to all products, regardless of category. Use this for attributes that every product needs, such as product title, description, brand, EAN, or main image URL.
• Supply one or more ChannelNo values - the attribute is scoped to those specific categories only. Sellers only see this attribute when they have mapped products to one of the listed categories.

Examples:

• Number of seating places - only relevant for sofas and chairs. Supply the ChannelNo values for your Sofas and Chairs categories. Sellers in other categories never see this field.
• Lens strength (dioptre) - only relevant for glasses and optics. Scope this to your Glasses & Optics category. Setting it as a global attribute would create unnecessary noise for every other seller on your channel.
• Product title - relevant for every product on the channel. Leave CategoryChannelNoList empty so it applies globally.

Available API endpoints

The following endpoints are used to manage product content attribute definitions for your channel.

• Export or update attribute definitions: POST /v1/attributes/data
  Send your full list of product content attributes to ChannelEngine. Every call replaces the previous export entirely - always submit your complete, current attribute list.
• Retrieve stored attribute definitions: GET /v1/attributes/data
  Retrieve the attributes currently stored for your channel. Primarily useful during development to verify that a POST call landed correctly.

POST /v1/attributes/data

Use this endpoint to send your full list of attributes to ChannelEngine. Every call replaces the previous export entirely, so always submit your complete, current attribute list - not just what has changed.

Request body

Attribute item fields (inside Items)

Example request

This example shows three attributes: a global required text field for the product title, a category-scoped select field for the number of seating places, and a global select field with a pre-filled default option for country of production.

{
  "ChannelCategoryAttributeNo": null,
  "Items": [
    {
      "ChannelNo": "product-title",
      "Name": "Product title",
      "SystemName": null,
      "CategoryChannelNoList": [],
      "IsRequired": true,
      "Type": "TEXT",
      "ProductType": "SINGLE",
      "AttributeType": "STANDARD",
      "Options": null,
      "DefaultOption": null,
      "DefaultValue": null,
      "Unit": null,
      "Description": "The title shown on the product detail page. Maximum 250 characters."
    },
    {
      "ChannelNo": "seating-places",
      "Name": "Number of seating places",
      "SystemName": null,
      "CategoryChannelNoList": ["sofas", "chairs"],
      "IsRequired": false,
      "Type": "SELECT",
      "ProductType": "SINGLE",
      "AttributeType": "STANDARD",
      "Options": [
        { "ChannelNo": "1", "Name": "1" },
        { "ChannelNo": "2", "Name": "2" },
        { "ChannelNo": "3", "Name": "3" }
      ],
      "DefaultOption": null,
      "DefaultValue": null,
      "Unit": null,
      "Description": "The total number of people this product can seat."
    },
    {
      "ChannelNo": "country-of-production",
      "Name": "Country of production",
      "SystemName": null,
      "CategoryChannelNoList": [],
      "IsRequired": false,
      "Type": "SELECT",
      "ProductType": "SINGLE",
      "AttributeType": "STANDARD",
      "Options": [
        { "ChannelNo": "CN", "Name": "China" },
        { "ChannelNo": "DE", "Name": "Germany" },
        { "ChannelNo": "NL", "Name": "Netherlands" }
      ],
      "DefaultOption": { "ChannelNo": "CN", "Name": "China" },
      "DefaultValue": null,
      "Unit": null,
      "Description": "The country where this product was manufactured."
    }
  ]
}

GET /v1/attributes/data

Use this endpoint to retrieve the attributes currently stored for your channel. This is primarily useful during development to verify that a POST call landed correctly. It is not required in your regular production flow.

Before your first export, call GET /v1/attributes/data to check whether your channel already has default attributes stored. If it does, include them in your POST payload so they are not overwritten.

Response structure

The response wraps your attribute data inside a standard API envelope. The Content object mirrors the structure used in the POST request body.

Example response

{
  "Content": {
    "ChannelCategoryAttributeNo": null,
    "Items": [
      {
        "ChannelNo": "product-title",
        "Name": "Product title",
        "SystemName": "product-title",
        "CategoryChannelNoList": [],
        "IsRequired": true,
        "Type": "TEXT",
        "ProductType": "SINGLE",
        "AttributeType": "STANDARD",
        "Options": null,
        "DefaultOption": null,
        "DefaultValue": null,
        "Unit": null,
        "Description": "The title shown on the product detail page. Maximum 250 characters."
      }
    ]
  },
  "StatusCode": 1,
  "RequestId": null,
  "LogId": null,
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": null
}

Testing your export

1. Check what is already stored - call GET /v1/attributes/data before your first export. If default attributes are present and you rely on them in MappedFields, include them in your POST payload.
2. Send your attribute list - call POST /v1/attributes/data with your complete attribute definitions. A successful response returns "Success": true with ValidationErrors as null.
3. Verify the result - call GET /v1/attributes/data again and inspect Content.Items. The returned list should reflect your full export. Note that SystemName will be auto-populated with the value of ChannelNo wherever you left it empty.
4. Check the attributes in the ChannelEngine UI - open the channel on ChannelEngine, go to the Mappings step, and scroll below the Content Mapping section. Your exported attributes should appear with the correct names, types, and required/optional status.
5. Test category scoping - verify a category-specific attribute by checking it only appears for the correct category on ChannelEngine's seller interface. Attributes linked to a category should not be visible to sellers who have mapped their products to a different category.
6. Record your results - document the request and response in the test script spreadsheet provided by your ChannelEngine contact. Include RequestId and LogId from the response for any cases where you have questions.

Common issues

Next steps

• If you have not done so already, export your category hierarchy first via POST /v1/categories/list - category ChannelNo values must exist before you can reference them in CategoryChannelNoList.
• Export offer-related attributes (such as pricing and stock fields) via POST /v1/attributes/offer.
• Once sellers have completed their attribute mapping, verify the results by fetching products via GET /v2/products/data and inspecting the MappedFields object.
• Include RequestId and LogId from any response when contacting ChannelEngine Support about a specific API call.