Merchant API: how to retrieve the channelId

About this article

This article explains how to retrieve your channel IDs with the GET /v2/channel endpoint of the Merchant API, how the response is structured, and how to use the IDs in other Merchant API endpoints.

Table of contents

Introduction

Requirements

Available API endpoints

Channels and global channels

• Names and IDs
• Which ID to use

Retrieving your channels

• Response fields

Using channel IDs in other endpoints

• Informational: read data per channel
• Action: change data on a channel
• Stock updates and channel IDs

Testing your setup

Common issues

Next steps

Introduction

Many Merchant API endpoints ask for a channel ID (the number ChannelEngine uses to identify one of your marketplace connections). You need it to filter your returns by marketplace, or to see which products are listed on a specific marketplace. Looking up these IDs by hand does not scale, and hard-coding them makes your integration fragile.

The channels endpoint returns the full list in one call. Use it to find the ChannelId you need for other endpoints, to check which channels are enabled, or to keep a channel list in your own system in sync.

Requirements

• Tenant URL: the base URL is https://{tenant}.channelengine.net/api.
• Merchant API key: the unique code that identifies your account to ChannelEngine. Send it in the X-CE-KEY header. Find it at Settings, Merchant API keys.

Available API endpoints

One endpoint returns your channels.

• Retrieve channels: GET /v2/channels

Use this endpoint to retrieve the complete list of channels in your ChannelEngine account, grouped by global channel. The endpoint takes no parameters. You send your API key and receive the full list.

Channels and global channels

ChannelEngine uses two levels to describe a marketplace connection. The response groups them for you, so it helps to know the difference.

• GlobalChannelId - the ID of a global channel on ChannelEngine, with a specific country and language, e.g.: Amazon NL. A global channel has a CountryCode and a LanguageCode. The ChannelEngine team names the channel in GlobalChannelName and can change this name without notice to you.
• ChannelId - the ID of your instance of a global channel and is the ID that other Merchant API endpoints ask for. Your channel instance has an enabled or disabled status; you name it in ChannelName, and you can change this name in the ChannelEngine web interface at any time.

Names and IDs

Both levels have a name and an ID. They look similar, but they behave differently.

Which ID to use

Every channel belongs to a global channel. Therefore, every channel has both a GlobalChannelId and a ChannelId.

Use the ChannelId in filters, URLs, and request bodies of other Merchant API endpoints. Do not replace it with the GlobalChannelId.

Use the combination of GlobalChannelId and ChannelId only to identify channels in your own system when you have multiple channels of the same marketplace. For example, if you have three Amazon.de channels, they share one , GlobalChannelId and each has its own ChannelId. The combination tells you which overall channel a specific channel on your dashboard belongs to.

Retrieving your channels

1. Send a request to GET /v2/channels with your key in the X-CE-KEY header. You receive HTTP 200 with Success: true.
2. Read the global channels in Content. Each item has a Channels list with your channels for that global channel. Each channel shows its ChannelId, ChannelName, and IsEnabled value.
3. Store the IDs you need. Use the ChannelId in the endpoints described in Using channel IDs in other endpoints.

Example request

curl -X GET "https://{tenant}.channelengine.net/api/v2/channels" \
  -H "Accept: application/json" \
  -H "X-CE-KEY: YOUR_MERCHANT_API_KEY"

Example response

{
  "Content": [
    {
      "GlobalChannelId": 1,
      "GlobalChannelName": "Amazon NL",
      "CountryCode": "NL",
      "LanguageCode": "nl",
      "Channels": [
        {
          "ChannelId": 12,
          "ChannelName": "Amazon NL",
          "IsEnabled": true,
          "Reference": null
        }
      ]
    },
    {
      "GlobalChannelId": 2,
      "GlobalChannelName": "Bol.com",
      "CountryCode": "NL",
      "LanguageCode": "nl",
      "Channels": [
        {
          "ChannelId": 27,
          "ChannelName": "Bol.com",
          "IsEnabled": false,
          "Reference": null
        }
      ]
    }
  ],
  "Count": 2,
  "TotalCount": 2,
  "ItemsPerPage": 2,
  "StatusCode": 200,
  "Success": true
}

Response fields

Global channel fields

Each item in Content is a global channel.

Channel fields

Standard collection fields

Using channel IDs in other endpoints

You use a ChannelId in other Merchant API endpoints in one of two ways. Either you read data for a channel, or you change something on a channel. The ID appears in different places: in the URL path, in the query string, or in the request body. Filters that accept several IDs are called ChannelIds.

Endpoints for reading data per channel

These requests filter or look up data per channel. Almost all are GET requests, and nothing changes on ChannelEngine or on the marketplace.

Endpoints for changing data on a channel

For these requests, the channel ID tells ChannelEngine where to apply a change. These are POST, PUT, and DELETE requests, and the change applies to that channel only.

Stock updates 

The endpoints that update your stock, PUT /v2/offer/stock and PUT /v2/offer, work with a stock location ID and not with a channel ID. To find your stock location IDs, use GET /v2/stocklocations.

The only endpoint that enables you to manage stock limits on the channel level is the product-level stock limitations endpoint, POST /v2/offer/{channelId}/product-level-stock-limitations.

Testing your setup

Test in your development environment before you go live.

1. Call GET /v2/channels with your Merchant API key. Expect HTTP 200 and Success: true.
2. Compare the list with the channels in your ChannelEngine account. Expect each channel you use under its global channel, with the right IsEnabled value.
3. Use one ID in another call, e.g.: GET /v2/channels/{channelId}/products. Expect HTTP 200 with the products listed on that channel.

Common issues

Still stuck? Contact your ChannelEngine contact and include the RequestId and LogId from the response.

Next steps

• Managing returns via the Merchant API: filter your returns by channel with the ChannelIds parameter.
• Retrieving listed products via the Merchant API: see which products are listed on a channel.
• Managing orders via the Merchant API: fetch, acknowledge, and ship your orders.