Channel Management API: offer attributes

About this article

This article explains how to use the POST /v1/attributes/offer and GET /v1/attributes/offer endpoints in the Channel Management API to export and retrieve offer attribute definitions for your channel.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

• POST /v1/attributes/offer
• GET /v1/attributes/offer

Testing your export

Common issues

Next steps

Introduction

The /v1/attributes/offer endpoints are for offer attributes, which are the fields that describe the commercial terms of a listing, such as price, sale price, stock quantity, lead time, or shipping class. These are distinct from product content attributes (title, description, brand, and so on), which are managed separately via /v1/attributes/data.

If your channel requires merchants to map their offer data 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 data accordingly. Once mapped, these values are included in the offer data your channel receives.

The Channel Management API works at the channel level, not per merchant. A single call to POST /v1/attributes/offer makes your attribute list visible to every seller connected to your channel at once. Unlike content attributes, offer attributes apply globally across your entire catalogue, with no category scoping for offer fields.

Overview

Refer to the flowchart below to visualize how offer attribute definitions travel between your channel, ChannelEngine, and the merchant.

Requirements

• Access to the Channel Management API - this is not enabled by default. Request it from your ChannelEngine implementation contact.
• A Channel Management API key - this is separate from your Channel API key.

Available API endpoints

The following endpoints are available for managing offer attributes. Both are limited to 2 calls per 15 minutes, counted separately per endpoint URL.

• Export offer attributes: POST /v1/attributes/offer
  Use this endpoint to send your complete list of offer attribute definitions to ChannelEngine. Every call replaces the full set of stored offer attributes for your channel.
• Retrieve offer attributes: GET /v1/attributes/offer
  Use this endpoint to retrieve the full list of offer attributes currently stored for your channel. Use it during development to verify a previous export, or before running a new export to check what is already on file.

POST /v1/attributes/offer

Use this endpoint to export your complete list of offer attribute definitions to ChannelEngine. Every call replaces the full set of stored offer attributes for your channel. This is a purge-and-replace operation, not an incremental update.

Request body

The request body is a JSON object with a single top-level field:

Offer attribute item fields

Each object in Items defines one offer attribute:

Example request

The following example exports three offer attributes: a required net price field, an optional sale price field, and a required stock quantity field.

{
  "Items": [
    {
      "ChannelNo": "price",
      "Name": "Net price",
      "SystemName": "price",
      "IsRequired": true,
      "Type": "NUMBER",
      "ProductType": "SINGLE",
      "AttributeType": "PRICE",
      "Options": null,
      "DefaultOption": null,
      "DefaultValue": null,
      "Unit": null,
      "Description": "Net price excluding VAT, in the seller's local currency."
    },
    {
      "ChannelNo": "sale-price",
      "Name": "Sale price",
      "SystemName": "sale-price",
      "IsRequired": false,
      "Type": "NUMBER",
      "ProductType": "SINGLE",
      "AttributeType": "PRICE",
      "Options": null,
      "DefaultOption": null,
      "DefaultValue": null,
      "Unit": null,
      "Description": "Promotional price, if applicable. Must be lower than net price."
    },
    {
      "ChannelNo": "stock-quantity",
      "Name": "Stock quantity",
      "SystemName": "stock-quantity",
      "IsRequired": true,
      "Type": "NUMBER",
      "ProductType": "SINGLE",
      "AttributeType": "STANDARD",
      "Options": null,
      "DefaultOption": null,
      "DefaultValue": null,
      "Unit": null,
      "Description": "Available units in the seller's warehouse."
    }
  ]
}

Successful response

A successful call returns HTTP 200 with the following body:

{
  "StatusCode": 1,
  "RequestId": null,
  "LogId": null,
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": null
}

When Success is false, check ValidationErrors for details on which fields failed validation.

GET /v1/attributes/offer

Use this endpoint to retrieve the full list of offer attributes currently stored for your channel. This is primarily useful during development to verify that a previous POST call produced the expected result, and before running a new export to check what is already on file.

Response structure

The response wraps your offer attribute data inside a standard API envelope. The Content object contains the stored offer attribute list.

Example response

{
  "Content": {
    "Items": [
      {
        "ChannelNo": "price",
        "Name": "Net price",
        "SystemName": "price",
        "IsRequired": true,
        "Type": "NUMBER",
        "ProductType": "SINGLE",
        "AttributeType": "PRICE",
        "Options": null,
        "DefaultOption": null,
        "DefaultValue": null,
        "Unit": null,
        "Description": "Net price excluding VAT, in the seller's local currency."
      }
    ]
  },
  "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/offer before your first export. If default offer attributes are already present, include them in your POST payload to avoid overwriting them.
2. Send your offer attribute list - call POST /v1/attributes/offer with your complete attribute definitions. A successful response returns "Success": true with ValidationErrors as null.
3. Verify the result - call GET /v1/attributes/offer again and inspect Content.Items. The returned list should reflect your full export. Note that SystemName is auto-populated with the value of ChannelNo wherever you left it empty.
4. Check the attributes on ChannelEngine - open the channel on ChannelEngine and go to the Offer mappings tab. Your exported offer attributes should appear there with the correct names, types, and required/optional status. Attributes with AttributeType: PRICE appear in the Pricing step instead.
5. Test a seller mapping - in a test seller account connected to your channel, complete the offer attribute mapping and verify that the expected values flow through in the offer data your channel receives. Required attributes must have a mapped value before offers are sent. If a required attribute is unmapped, the offer is withheld and the seller sees a validation message.
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

• Export your product content attributes (title, description, brand, and so on) via POST /v1/attributes/data if you have not already done so.
• If any of your content attributes are category-specific, export your category hierarchy first via POST /v1/categories/list so the correct ChannelNo values are available for CategoryChannelNoList.
• Once sellers have completed their offer mapping, verify the results by fetching offer data through the Channel API and confirming the expected fields are present.
• Include RequestId and LogId from any response when contacting ChannelEngine Support about a specific API call.