Merchant API: create a failed order export notification

About this article

This article explains how to use POST /v2/orders/mark-export-as-failed to trigger a notification in ChannelEngine's notification center, alerting all users in your tenant that a given order could not be exported to your merchant system.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

• Endpoint: create a failed order export notification

Example request

Common issues

Next steps

Introduction

When your merchant system retrieves orders from ChannelEngine and the export to your system fails — for example, because your system is unreachable, a database write fails, or a required field cannot be parsed — you can use POST /v2/orders/mark-export-as-failed to send a notification through ChannelEngine's notification center.

Calling this endpoint triggers a notification that is visible to all users in your ChannelEngine tenant, alerting them that one or more orders were not successfully exported to the merchant system. This gives your team visibility into the failure directly in ChannelEngine, without requiring them to check external logs or wait for someone to report the issue manually.

Use this endpoint as part of your error handling logic. Once the export failure is resolved, include the affected orders in your next export cycle and acknowledge them as normal.

Overview

Refer to the diagram below to visualize how a failed order export notification fits into the order retrieval flow.

Requirements

Before making your first API call, you need the following:

• A ChannelEngine account with at least one channel connected.
• A Merchant API key generated on ChannelEngine at Settings, Merchant API keys.
• Your base API URL constructed from your account subdomain: https://{your-subdomain}.channelengine.net/api.
• One or more ChannelEngine order IDs for the orders that failed to export. These are returned in the response body of GET /v2/orders/new as the Id field on each order.

Authentication

Every request to the Merchant API must include your API key in the x-ce-key request header:

x-ce-key: your-api-key-here

Available API endpoints

This article covers the following endpoint:

• Create a failed order export notification: POST /v2/orders/mark-export-as-failed
  Triggers a notification in ChannelEngine's notification center for all users in your tenant, indicating that the specified orders could not be exported to your merchant system.

Endpoint: create a failed order export notification

POST /v2/orders/mark-export-as-failed sends a notification via ChannelEngine's notification center to all users in your tenant. The notification identifies the affected orders and signals that the export to the merchant system did not succeed. It does not change the order status or affect the marketplace.

Request body

The request body is a JSON object containing the identifier type and an array of order objects. Each object in the array identifies one order for which a notification should be sent.

Response codes

Example request

The example below sends a failed export notification for two orders. Replace the Identifier values with the actual IDs from your order retrieval response.

POST https://{your-subdomain}.channelengine.net/api/v2/orders/mark-export-as-failed
x-ce-key: your-api-key-here
Content-Type: application/json

{
  "IdentifierType": "ORDER_ID",
  "Models": [
    {
      "Identifier": 4829301,
      "FailExportMessage": "Database write failed: connection timeout"
    },
    {
      "Identifier": 4829302,
      "FailExportMessage": "Order line quantity could not be parsed"
    }
  ]
}

A successful response looks like this:

{
  "Success": true,
  "Count": 2,
  "TotalCount": 2,
  "ItemsPerPage": 10,
  "StatusCode": 200,
  "LogId": "01JXXXXXXXXXXXXXXXXXXXXXX",
  "RequestId": "01JXXXXXXXXXXXXXXXXXXXXXX"
}

After a successful call, all users in your ChannelEngine tenant see a notification in the Notification center indicating that the specified orders were not exported to the merchant system.

Common issues

Next steps

• After resolving the export issue, include the previously failed orders in your next retrieval and acknowledgement cycle via GET /v2/orders/new and POST /v2/orders/acknowledge.
• For guidance on handling API errors and response codes more broadly, check out Merchant API: errors and response codes.
• For best practices on building resilient order export flows, including retry logic and error classification, check out Merchant API: best practices.
• For the full order management workflow — retrieval, acknowledgement, shipments, and invoices — check out Merchant API: orders.
• Include the RequestId and LogId values from any response when contacting ChannelEngine Support about a specific API call.