Merchant API: cancelations

About this article

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

Table of contents

About this article

Introduction

Overview

Requirements

Available API endpoints

Endpoint: retrieve cancelations

Endpoint: submit a cancelation

Handling channel cancelations

• Flow: request-based cancelation
• Flow: enforced cancelation

Common issues

Next steps

Introduction

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

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

What is a cancelation?

A cancelation 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 cancelation endpoints.
• If the order has a shipment on ChannelEngine, use the returns endpoints.

Merchant cancelations and channel cancelations

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

Merchant cancelation

The seller initiates the cancelation, 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 cancelation on ChannelEngine.
• ChannelEngine forwards the cancelation to the marketplace.
• IsMerchantCreator is true.

Channel cancelation

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

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

Request-based cancelations and enforced cancelations

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

Request-based cancelation

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

• The marketplace sends a cancelation request to ChannelEngine.
• If the order is already in progress, ChannelEngine flags the order to show that a cancelation 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 cancelation.
• ChannelEngine forwards the confirmation to the marketplace.

Enforced cancelation

The marketplace enforces the cancelation 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 canceled.
• 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 cancelation already exists for an order and your system then submits a shipment for that order, the shipment call returns an error because a canceled order is no longer in a shippable state.

Overview

Refer to the flowchart below to visualize how cancelations 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 cancelation references: generate a unique MerchantCancellationNo for every cancelation and never reuse it.
• Timely shipments: record shipments on ChannelEngine at the moment of carrier handover, especially on marketplaces with enforced cancelations.

Available API endpoints

Use the following endpoints to manage cancellations:

• Retrieve cancelations: GET /v2/cancellations/merchant

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

• Submit a cancelation: POST /v2/cancellations

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

Endpoint: retrieve cancelations

• Retrieve cancelations: GET /v2/cancellations/merchant

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

Query parameters

Response fields

Endpoint: submit a cancelation

• Submit a cancelation: POST /v2/cancellations

Use this endpoint to register a cancelation for an order that was not shipped yet. You use it in two scenarios: you cancel the order yourself (merchant cancelation), or you confirm a cancelation request from the marketplace (channel cancelation). 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 cancelation.

Cancelation reason codes

Example requests

Merchant cancelation (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 cancelation 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 cancelations

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 cancelations. 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 cancelations

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

Flow: request-based cancelation

When the marketplace sends you a cancelation request, ChannelEngine does not create a cancelation 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 cancelation, 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 cancelation with POST /v2/cancellations (See the note below.)
4. Optionally, verify the result with GET /v2/cancellations/merchant, filtered by your MerchantCancellationNo.

Flow: enforced cancelation

When the channel sends an enforced cancelation, 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 cancelations 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 cancelation created by the channel.
3. Stop fulfillment of the canceled 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 cancelations in your sandbox (test your cancelation integration before you go live).
• Merchant API: shipments (create shipments to prevent unintended cancelations on marketplaces with enforced cancelations).
• Merchant API: orders (retrieve and acknowledge orders, detect cancelation requests, and check ChannelOrderSupport).
• Merchant API: returns (handle post-shipment issues through the returns flow).
• ChannelEngine: cancelations (handle cancelations via the ChannelEngine web interface).