Merchant API: create a failed cancellation 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 cancellation could not be exported to the channel. It covers when to call the endpoint, how to identify cancellations, 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 cancellation exports as failed

Example request

Common issues

Next steps

Introduction

When your merchant system creates a cancellation with POST /v2/cancellations, ChannelEngine exports the cancellation to the channel. If this does not result in the cancellation 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 cancellation export failed notification (notification type CHANNEL_CANCELLATION_EXPORT_FAILED) in the notification center on ChannelEngine. The notification identifies the affected cancellations, 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 cancellation 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 cancellation was not exported to the channel. Use POST /v2/cancellations/mark-export-as-failed in your error handling logic for these cancellations. In general, if you identify that your cancellation was not exported to the channel, contact ChannelEngine Support.

Overview

Refer to the diagram below to visualize how a notification about a cancellation 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 cancellation numbers for the cancellations that were not exported to the channel. Use the MerchantCancellationNo that you provided when you created the cancellation 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 cancellation exports as failed: POST /v2/cancellations/mark-export-as-failed
  Creates a cancellation export failed notification in the notification center on ChannelEngine for the specified cancellations, including a failure message for each cancellation.

Endpoint: mark cancellation exports as failed

POST /v2/cancellations/mark-export-as-failed creates a cancellation export failed notification in the notification center on ChannelEngine for one or more cancellations. You call this endpoint. Each cancellation is identified by its cancellation 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 cancellation being exported to the channel. Do not call it for cancellations that were exported successfully. Additionally, calling the endpoint does not modify the existing cancellation.

Request body

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

Response codes

Example request

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

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 cancellation for an order on ChannelEngine.
• GET /v2/cancellations/merchant - retrieve cancellations from ChannelEngine and reconcile your records.
• For an overview of cancellations on ChannelEngine, check out ChannelEngine: cancellations.
• 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 cancellation export, contact the ChannelEngine Support team.