Merchant API: notifications

About this article

This article explains how to retrieve your ChannelEngine notifications via the Merchant API with GET /v2/notifications, how to filter and paginate the results, and how to interpret each notification type.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

• Parameters
• Step by step
• Reading the response
• Response fields
• Notification types

Common workflows

Testing the endpoint

Example requests

Common errors

Next steps

Introduction

An order fails to import, a stock update is rejected, or a marketplace connection is about to expire. ChannelEngine raises a notification for each of these events, so you know what needs your attention.

The notifications endpoint lets you pull those notifications into your own systems. You can poll for new failures, check what happened to a specific order, return, or shipment, and route alerts to the right team without logging in to ChannelEngine.

Overview

Refer to the diagram below to visualize how notifications travel between the channel, ChannelEngine, and your system.

You can narrow the results in three ways:

• By date: return only notifications created within a time window.
• By type: return only the kinds of notifications you care about, e.g.: failed order imports.
• By reference: return notifications for specific orders, returns, or shipments, using your own numbers or the channel numbers.

Requirements

• Your tenant URL: the base URL is https://{tenant}.channelengine.net/api.
• A 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.

X-CE-KEY: your-merchant-api-key

Available API endpoints

• Retrieve notifications: GET /v2/notifications

Use this endpoint to retrieve your ChannelEngine notifications. Without filters, the endpoint returns your notifications page by page.

Parameters

All parameters are optional and go in the query string.

Step by step

1. Choose what you want to see. Decide on a time window, one or more notification types, or the order, return, or shipment numbers you are investigating. If you are not sure yet, start with a short time window and no other filters.
2. Send the request to GET /v2/notifications with your key in the X-CE-KEY header and your filters in the query string. You receive HTTP 200 with Success: true.
3. Read the notifications in Content. Use Type to decide what to do, and Subject and Message for the details. If TotalCount is higher than Count, request the next page.

Reading the response

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

Response fields

Response content

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

Collection fields in the response

Response example

{
  "Content": [
    {
      "Id": 145018,
      "Read": false,
      "CreatedAt": "2026-10-02T07:29:05.6408797+00:00",
      "Message": "\n\n\n\n\n    <div style=\"white-space: pre-line\" class=\"alert alert-warning\">Some Shipments (4) with ids [76,77,78,91] are still on a PENDING status</div>\n\n",
      "Subject": "Shipment still on PENDING",
      "Count": 1,
      "Type": "CHANNEL_SHIPMENT_TOO_LONG_ON_PENDING"
    }
  ],
  "Count": 1,
  "TotalCount": 1,
  "ItemsPerPage": 1,
  "StatusCode": 200,
  "RequestId": null,
  "LogId": null,
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": null
}

Notification types

Every notification has a Type. Use these values in the Types filter. Most names tell you what happened. Types that end in _FAILED usually mean something needs your attention, while types such as _NEW or _SUCCEEDED are informational.

Notification types

Common workflows

Poll for new failures

Run a scheduled job that checks for notifications created since the last run.

1. Set FromDate to the time of your previous run and ToDate to the current time.
2. Add the failure types you want to monitor in Types, and request every page.
3. Store the ToDate of this run and use it as FromDate in the next run.

Find out what happened to an order, return, or shipment

Pass the reference in MerchantOrderNos, ChannelOrderNos, MerchantReturnNos, ChannelReturnNos, or MerchantShipmentNos. This is the quickest way to see why a specific order did not reach your system or why a shipment update failed.

Testing the endpoint

Test in your development environment before you go live.

1. Call the endpoint without filters. Expect HTTP 200 and Success: true. If your account has notifications, they appear in Content.
2. Add a Types filter for a type you know occurred, e.g.: CHANNEL_ORDER_NEW. Expect every item in Content to have that Type.
3. Add a date window that contains one known notification. Expect TotalCount to drop, and every CreatedAt to fall inside your window.
4. Compare the result with the notifications on ChannelEngine. Expect the subject, message, and creation time to match what you see in the interface.

Example requests

Filter by date and type (cURL)

curl -X GET "https://{tenant}.channelengine.net/api/v2/notifications?FromDate=2026-10-01T00:00:00Z&ToDate=2026-10-02T00:00:00Z&Types=CHANNEL_ORDER_IMPORT_FAILED&Types=MERCHANT_STOCK_UPDATE_FAILED&Page=1" \
  -H "Accept: application/json" \
  -H "X-CE-KEY: YOUR_MERCHANT_API_KEY"

Filter by order reference (cURL)

curl -X GET "https://{tenant}.channelengine.net/api/v2/notifications?MerchantOrderNos=ORDER-1001&MerchantOrderNos=ORDER-1002" \
  -H "Accept: application/json" \
  -H "X-CE-KEY: YOUR_MERCHANT_API_KEY"

Retrieve all pages (Python)

import requests

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

def get_notifications(from_date, to_date, types=None):
    page = 1
    while True:
        params = {"FromDate": from_date, "ToDate": to_date, "Page": page}
        if types:
            params["Types"] = types  # requests repeats the parameter for each value
        response = requests.get(f"{BASE}/v2/notifications", headers=HEADERS, params=params)
        response.raise_for_status()
        data = response.json()
        if not data["Success"]:
            raise RuntimeError(data.get("Message"))
        yield from (data["Content"] or [])
        if page * data["ItemsPerPage"] >= data["TotalCount"]:
            break
        page += 1

failures = list(get_notifications(
    "2026-10-01T00:00:00Z",
    "2026-10-02T00:00:00Z",
    ["CHANNEL_ORDER_IMPORT_FAILED", "MERCHANT_STOCK_UPDATE_FAILED"],
))

Common errors

If you are still stuck, contact your ChannelEngine contact and include the RequestId and LogId from the response.

Next steps

• Managing orders via the Merchant API: fetch, acknowledge, and ship your orders.
• Authentication and rate limits: Merchant API key setup and request throttling.