Merchant API: listed products

About this article

This article explains how to use the GET /v2/channels/{channelId}/products endpoint of the Merchant API to retrieve the listed products of a channel, including the export status and the channel status of each product.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

Endpoint: retrieve listed products

• Parameters
• Step by step
• Example requests
• Reading the response
• Status values

Common workflows

Testing the endpoint

Common issues

Next steps

Introduction

You store your products on ChannelEngine and select them to list on a channel. Next, you want to know what happened: did the export run, and did the channel accept the products?

The channels endpoint answers both questions. The endpoint returns the export status and the channel status for each product on a channel, plus the channel product reference, the last price, and the last stock that ChannelEngine exported. Use the channels endpoint to confirm a sync, audit a whole channel, or spot products that need attention.

Overview

Refer to the flowchart below to visualize how listed product statuses travel between the channel, ChannelEngine, and your system.

The GET /v2/channels endpoint reports two kinds of statuses for every product:

• Export status: what ChannelEngine did with the product on the last export (e.g.: created or updated).
• Channel status: what the channel reports back about the product (e.g.: published or not published).

The response also includes products that ChannelEngine deleted earlier and that are now set to be created again.

Requirements

• Tenant URL: the base URL is https://{tenant}.channelengine.net/api.
• Merchant API key: a unique code that identifies your account to ChannelEngine. Send it in the X-CE-KEY header. A Channel API key does not work here.
• Channel ID: call GET /v2/channels. Each global channel in the response has a Channels array, and every item in it has a ChannelId. Use that value, not the GlobalChannelId.
• Selected products: only products in the product selection of the channel appear in the response.

Available API endpoints

Use these endpoints to find and check the listed products of a channel.

• Retrieve channels: GET /v2/channels
  Use this endpoint to find the ChannelId of the channel you want to check.
• Retrieve listed products: GET /v2/channels/{channelId}/products
  Use this endpoint to retrieve the listed products of a channel, with the export status, the channel status, the last exported price, and the last exported stock of each product.

Endpoint: retrieve listed products

Send a GET request to /v2/channels/{channelId}/products with your Merchant API key in the X-CE-KEY header.

Parameters

Step by step

1. Call GET /v2/channels to find your channel ID. Note the ChannelId of the channel you want to check, found under Channels in each global channel.
2. Send the request to GET /v2/channels/{channelId}/products with your key in the X-CE-KEY header. Add MerchantProductNos to check specific SKUs, or Page to move through a large catalog. You receive HTTP 200 with Success: true.
3. Read ExportStatus and ChannelStatus for each product. Refer to Status values for the meaning of each value.

Example requests

cURL

curl -X GET "https://{tenant}.channelengine.net/api/v2/channels/123/products?Page=1&MerchantProductNos=SHIRT-RED-M&MerchantProductNos=SHIRT-BLUE-L" \
  -H "Accept: application/json" \
  -H "X-CE-KEY: YOUR_MERCHANT_API_KEY"

Python

import requests

BASE = "https://your-tenant.channelengine.net/api"
HEADERS = {"X-CE-KEY": "YOUR_MERCHANT_API_KEY", "Accept": "application/json"}

def get_listed_products(channel_id):
    page = 1
    while True:
        response = requests.get(
            f"{BASE}/v2/channels/{channel_id}/products",
            headers=HEADERS,
            params={"Page": page},
        )
        response.raise_for_status()
        data = response.json()
        if not data["Success"]:
            raise RuntimeError(data.get("Message"))
        yield from data["Content"]
        if page * data["ItemsPerPage"] >= data["TotalCount"]:
            break
        page += 1

not_published = [
    p for p in get_listed_products(123)
    if p["ChannelStatus"] == "NOT_PUBLISHED"
]

Reading the response

The response is a paginated collection. Each item in Content is one listed product.

Around the items, the response contains the standard collection fields:

Example response for GET /v2/channels/123/products?Page=1:

{
  "Content": [
    {
      "MerchantProductNo": "SHIRT-RED-M",
      "Ean": "8715342024592",
      "ChannelProductNo": "9876543210",
      "ExportStatus": "CREATED",
      "ChannelStatus": "PUBLISHED",
      "LastExportedPrice": 24.99,
      "LastExportedStock": 12
    },
    {
      "MerchantProductNo": "SHIRT-BLUE-L",
      "Ean": "8715342024608",
      "ChannelProductNo": null,
      "ExportStatus": "CREATE_FAILED",
      "ChannelStatus": "INVALID_ON_CREATE",
      "LastExportedPrice": 24.99,
      "LastExportedStock": 0
    }
  ],
  "Count": 2,
  "TotalCount": 1500,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "Success": true
}

Status values

These are the values that the API returns. They correspond to the statuses you see in Listed products on ChannelEngine.

ExportStatus

ChannelStatus

Common workflows

Check specific products after a sync

Pass the SKUs you just updated in MerchantProductNos. This is faster than paging through the whole channel.

Audit a full channel

1. Request Page=1 and read TotalCount and ItemsPerPage.
2. Calculate the number of pages: TotalCount / ItemsPerPage, rounded up.
3. Request each page from 1 to the last page and collect the items.

Testing the endpoint

Test in your development environment before you go live.

1. Call the endpoint without filters for a channel that has selected products. Expect HTTP 200, Success: true, and items in Content.
2. Call it again with one SKU in MerchantProductNos. Expect only that product in the response and a TotalCount of 1.
3. Compare the result with Listed products for the same channel on ChannelEngine. Expect the export status, channel status, price, and stock to match the values in the UI.

Common issues

If the issue persists, contact ChannelEngine Support and include the RequestId and LogId from the response.

Next steps

• Managing products via the Merchant API: submit and update product content.
• Managing offers via the Merchant API: update stock and price on your products.
• Authentication and rate limits: set up your Merchant API key and learn about request throttling.