Merchant API: create a failed cancelation export notification

About this article

This article explains how to use POST /v2/cancellations/mark-export-as-failed to trigger a notification in ChannelEngine's notification center, alerting the users in your tenant that a cancelation could not be exported to the channel. It covers when to call the endpoint, how to identify cancelations, how to send a single or bulk request, and how to fix common errors.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

• Endpoint: mark cancelation exports as failed

Example request

Common issues

Next steps

Introduction

When your merchant system creates a cancelation with POST /v2/cancellations, ChannelEngine exports the cancelation to the channel. If this does not result in the cancelation being exported to the channel, you can use POST /v2/cancellations/mark-export-as-failed from your merchant system to send a notification through ChannelEngine's notification center.

Calling this endpoint creates a cancelation export failed notification (notification type CHANNEL_CANCELLATION_EXPORT_FAILED) in the notification center on ChannelEngine. The notification identifies the affected cancelations, includes the failure message that you provide, and is visible to all users of your tenant, as indicated by your base API URL. This gives your team visibility into the failure directly on ChannelEngine, without requiring them to check external logs or wait for someone to report the issue manually.

To detect whether a cancelation that you created with POST /v2/cancellations was exported to the channel, retrieve it with GET /v2/cancellations/merchant and the MerchantCancellationNos parameter. If your MerchantCancellationNo is not in the response, the cancelation was not exported to the channel. Use POST /v2/cancellations/mark-export-as-failed in your error handling logic for these cancelations. In general, if you identify that your cancelation was not exported to the channel, contact ChannelEngine Support.

Overview

Refer to the diagram below to visualize how a notification about a cancelation that is not exported to the channel is created on ChannelEngine.

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 cancelation numbers for the cancelations that were not exported to the channel. Use the MerchantCancellationNo that you provided when you created the cancelation with POST /v2/cancellations.

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:

• Mark cancelation exports as failed: POST /v2/cancellations/mark-export-as-failed
  Creates a cancelation export failed notification in the notification center on ChannelEngine for the specified cancelations, including a failure message for each cancelation.

Endpoint: mark cancelation exports as failed

POST /v2/cancellations/mark-export-as-failed creates a cancelation export failed notification in the notification center on ChannelEngine for one or more cancelations. You call this endpoint. Each cancelation is identified by its cancelation ID and requires a failure message.

When to use this endpoint

Call the endpoint from your merchant system when a call to POST /v2/cancellations does not result in the cancelation being exported to the channel. Do not call it for cancelations that were exported successfully. Additionally, calling the endpoint does not modify the existing cancelation.

Request body

The request body is a JSON object containing the identifier type and an array of cancelation objects. Each object in the array identifies one cancelation and contains its failure message.

Response codes

Example request

The example below creates a notification for two cancelations that were not exported to the channel. Replace the Identifier values with the actual cancelation numbers of your cancelations.

POST https://{your-subdomain}.channelengine.net/api/v2/cancellations/mark-export-as-failed
X-CE-KEY: your-api-key-here
Content-Type: application/json

{
  "IdentifierType": "CANCELLATION_ID",
  "Models": [
    {
      "Identifier": "MC-2026-004817",
      "FailExportMessage": "Cancelation MC-2026-004817 was not exported to SuperShop: GET /v2/cancellations/merchant did not return MerchantCancellationNo MC-2026-004817 within 30 minutes after POST /v2/cancellations."
    },
    {
      "Identifier": "MC-2026-004818",
      "FailExportMessage": "Cancelation MC-2026-004818 was not exported to SuperShop: GET /v2/cancellations/merchant did not return MerchantCancellationNo MC-2026-004818 within 30 minutes after POST /v2/cancellations."
    }
  ]
}

Common issues

Next steps

• POST /v2/cancellations - create a cancelation for an order on ChannelEngine.
• GET /v2/cancellations/merchant - retrieve cancelations from ChannelEngine and reconcile your records.
• For an overview of cancelations on ChannelEngine, check out ChannelEngine: cancelations.
• For details on your rate limits, check out Merchant API: rate limits.
• 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 export flows, including retry logic and error classification, check out Merchant API: best practices.
• For the equivalent endpoint for orders, which reports a failed export to the merchant system, check out Merchant API: create a failed order export notification.
• If you cannot resolve your failed cancelation export, contact the ChannelEngine Support team.