Merchant API: cancellations

About this article

This article explains how cancellations work on ChannelEngine and how to handle them with the Merchant API. It covers how to retrieve cancellation records from ChannelEngine, accept cancellation requests from a marketplace, and how to submit a merchant cancellation.

Table of contents

About this article

Introduction

Overview

Requirements

Available API endpoints

Endpoint: retrieve cancellations

Endpoint: submit a cancellation

Handling channel cancellations

• Flow: request-based cancellation
• Flow: enforced cancellation

Common issues

Next steps

Introduction

Cancellations are a routine part of order management. Buyers change their minds, items go out of stock, or a marketplace enforces a cancellation before the order ships. The cancellation endpoints of the Merchant API let you retrieve cancellations, submit cancellations to the marketplace, and flag to the rest of the users on your ChannelEngine tenant cancellation exports that failed.

This article explains the difference between merchant cancellations and channel cancellations, and how the cancellation model of a marketplace affects the design of your integration.

What is a cancellation?

A cancellation applies only to orders that are not shipped yet. Once a shipment for an order exists on ChannelEngine, you can no longer cancel that order. Post-shipment issues, such as a return requested by the buyer, are handled through the returns flow instead.

The key difference is timing:

• If the order has no shipment on ChannelEngine, use the cancellation endpoints.
• If the order has a shipment on ChannelEngine, use the returns endpoints.

Merchant cancellations and channel cancellations

Cancellations originate from one of two directions, and your integration needs to handle both.

Merchant cancellation

The seller initiates the cancellation, typically because an item is out of stock, damaged, or cannot be fulfilled for another reason.

• Your system detects the need to cancel.
• You call POST /v2/cancellations to register the cancellation on ChannelEngine.
• ChannelEngine forwards the cancellation to the marketplace.
• IsMerchantCreator is true.

Channel cancellation

The marketplace or the buyer initiates the cancellation. Depending on the marketplace, ChannelEngine either receives a cancellation request that you need to act on, or it directly applies an enforced cancellation. See Request-based cancellations and enforced cancellations.

• In response to a cancellation request, ChannelEngine flags the order, and you retrieve the request through the /v2/orders endpoints.
• Once a channel cancellation exists on ChannelEngine, you retrieve it with GET /v2/cancellations/merchant.
• IsMerchantCreator is false.

Request-based cancellations and enforced cancellations

Marketplaces do not all handle cancellations in the same way. Cancellation behavior depends on the marketplace. Your integration needs to account for both models: request-based cancellations and enforced cancellations. 

Request-based cancellation

The marketplace sends a cancellation request to ChannelEngine. The order stays active until you confirm the cancellation.

• The marketplace sends a cancellation request to ChannelEngine.
• If the order is already in progress, ChannelEngine flags the order to show that a cancellation was requested. You retrieve this flag via the GET /v2/orders endpoint. In the order response, check the CancellationRequestedQuantity field.
• Your system detects the request and stops fulfillment.
• You call POST /v2/cancellations to confirm the cancellation.
• ChannelEngine forwards the confirmation to the marketplace.

Enforced cancellation

The marketplace enforces the cancellation directly, at any point before the order is marked as delivered, without waiting for confirmation from the seller. This model is common on marketplaces such as Lazada, Shopee, noon, Namshi, and TikTok Shop.

• If no shipment exists on ChannelEngine, ChannelEngine automatically marks the order as cancelled.
• This happens regardless of the internal fulfillment state of the seller.
• ChannelEngine does not check whether the parcel physically left the warehouse. It only checks whether a shipment exists on ChannelEngine.*

*Record shipments on ChannelEngine as soon as the parcel is handed to the carrier, not in a later batch step. If an enforced cancellation already exists for an order and your system then submits a shipment for that order, the shipment call returns an error because a cancelled order is no longer in a shippable state.

Overview

Refer to the flowchart below to visualize how cancellations travel between the marketplace, ChannelEngine, and the merchant.

Requirements

• Merchant API key: the key of your ChannelEngine account. Refer to Merchant API: main resources for more information on the Merchant API.
• Orders on ChannelEngine: the order that you cancel must exist on ChannelEngine and must not have a shipment yet.
• Unique cancellation references: generate a unique MerchantCancellationNo for every cancellation and never reuse it.
• Timely shipments: record shipments on ChannelEngine at the moment of carrier handover, especially on marketplaces with enforced cancellations.

Available API endpoints

Use the following endpoints to manage cancellations:

• Retrieve cancellations: GET /v2/cancellations/merchant

Use this endpoint to retrieve cancellations that exist on ChannelEngine, both the ones you submitted and the ones created by a channel. This endpoint does not return pending cancellation requests. Those are flagged on the order.

• Submit a cancellation: POST /v2/cancellations

Use this endpoint to submit a full or partial cancellation for an order that is not shipped yet.

Endpoint: retrieve cancellations

• Retrieve cancellations: GET /v2/cancellations/merchant

Use this endpoint to retrieve cancellations from ChannelEngine and to reconcile your records. The response contains cancellations created by you (IsMerchantCreator is true) and cancellations created by a channel (IsMerchantCreator is false).

Query parameters

Response fields

Endpoint: submit a cancellation

• Submit a cancellation: POST /v2/cancellations

Use this endpoint to register a cancellation for an order that was not shipped yet. You use it in two scenarios: you cancel the order yourself (merchant cancellation), or you confirm a cancellation request from the marketplace (channel cancellation). The IsMerchantCreator field tells ChannelEngine which scenario applies.

Request body

Reason codes

The ReasonCode field accepts one of the following values. Always provide the code that most accurately describes the reason for the cancellation.

Cancellation reason codes

Example requests

Merchant cancellation (item out of stock)

POST /v2/cancellations

{
  "MerchantCancellationNo": "CANC-20260817-001",
  "MerchantOrderNo": "ORD-98765",
  "Lines": [
    {
      "MerchantProductNo": "SKU-001",
      "Quantity": 2
    }
  ],
  "ReasonCode": "NOT_IN_STOCK",
  "Reason": "Item discontinued, no stock available",
  "IsMerchantCreator": true
}

Confirming a cancellation request from the marketplace

POST /v2/cancellations

{
  "MerchantCancellationNo": "CANC-20260817-002",
  "MerchantOrderNo": "ORD-98766",
  "Lines": [
    {
      "MerchantProductNo": "SKU-002",
      "Quantity": 1
    }
  ],
  "ReasonCode": "CLIENT_CANCELLED",
  "IsMerchantCreator": false
}

Partial cancellations

To cancel an order partially, include only the lines and quantities that you cancel. The remaining lines stay active, and you can still ship them. Not every marketplace supports partial cancellations. Check the relevant marketplace guide to find out whether you need to cancel the full order or whether you can cancel individual lines.

Handling channel cancellations

How you detect a channel cancellation depends on the cancellation model of the marketplace.

Flow: request-based cancellation

When the marketplace sends you a cancellation request, ChannelEngine does not create a cancellation record until you confirm the request. Detect the request via the order endpoints instead:

1. Retrieve your orders as part of your regular order sync with GET /v2/orders. When a channel requests a cancellation, ChannelEngine flags the order, and the order lines show the requested quantity in CancellationRequestedQuantity.
2. Stop fulfillment of the requested lines in your warehouse management system (WMS) or enterprise resource planning (ERP) system.
3. Confirm the cancellation with POST /v2/cancellations (See the note below.)
4. Optionally, verify the result with GET /v2/cancellations/merchant, filtered by your MerchantCancellationNo.

Flow: enforced cancellation

When the channel sends an enforced cancellation, ChannelEngine cancels the order automatically if no shipment exists. You do not need to confirm it, but your system still needs to stop fulfillment.

1. Retrieve cancellations regularly with GET /v2/cancellations/merchant and set UpdatedSince to the timestamp of your last successful poll.
2. Check the IsMerchantCreator field of each record in the response. A value of false identifies a cancellation created by the channel.
3. Stop fulfillment of the cancelled order or lines in your WMS or ERP system.

POST /v2/cancellations/mark-export-as-failed

{
  "IdentifierType": "CANCELLATION_ID",
  "Models": [10042, 10043]
}

Common issues

Next steps

• Merchant API: testing cancellations in your sandbox (test your cancellation integration before you go live).
• Merchant API: shipments (create shipments to prevent unintended cancellations on marketplaces with enforced cancellations).
• Merchant API: orders (retrieve and acknowledge orders, detect cancellation requests, and check ChannelOrderSupport).
• Merchant API: returns (handle post-shipment issues through the returns flow).
• ChannelEngine: cancellations (handle cancellations via the ChannelEngine web interface).