Merchant API: testing cancellations in your sandbox

About this article

This article describes the tests to run before you go live with the cancellation endpoints of the Merchant API, and the checklist to confirm with your ChannelEngine implementation contact. For background on how cancellations work, refer to Merchant API: cancellations.

Table of contents

About this article

Introduction

Requirements

Test 1: retrieve cancellations

Test 2: submit a cancellation

Sign-off checklist

Next steps

Introduction

Run these tests to confirm that your cancellation integration works end to end. Work through the tests in order, log the results, and share them with your ChannelEngine implementation contact before sign-off.

Requirements

• Staging or sandbox environment: a ChannelEngine staging environment or dedicated sandbox.
• Merchant API key: the key of your sandbox environment.
• Test orders: at least two acknowledged test orders without a shipment.

Test 1: retrieve cancellations

Goal: confirm that your integration retrieves cancellation records from ChannelEngine and correctly distinguishes merchant cancellations from channel cancellations.

Create a merchant cancellation and a test channel cancellation. To simulate a channel cancellation, create a test cancellation on ChannelEngine via the web interface. Create a cancellation on a test order, select Channel (Test) in the Created by field, and the cancellation is created with IsMerchantCreator set to false. 

1. Open a test order on ChannelEngine and click Create cancellation. Select Merchant in Created by and save the cancellation.
2. Open a second test order, click Create cancellation, select Channel (Test) in Created by, and save the cancellation.
3. Call GET /v2/cancellations/merchant without filters. Expected: HTTP 200 and both cancellations in the response.
4. Call the endpoint again with UpdatedSince set to a recent timestamp. Expected: only cancellations updated since that timestamp are returned.
5. Check the IsMerchantCreator field of each record. Expected: your integration routes the record with IsMerchantCreator set to false to your stop-fulfillment workflow, and treats the record with true as your own cancellation.

Record your results: HTTP status, polling by UpdatedSince works (yes or no), and IsMerchantCreator correctly identified (yes or no).

Test 2: submit a cancellation

Goal: confirm that your integration submits a merchant cancellation correctly.

1. Retrieve an acknowledged test order that has no shipment and note its MerchantOrderNo.
2. Call POST /v2/cancellations with IsMerchantCreator set to true, a ReasonCode, and all order lines at their full quantities. Expected: a successful response, and the cancellation is queued for export to the marketplace.
3. Call GET /v2/cancellations/merchant filtered by your MerchantCancellationNo. Expected: the cancellation appears with the matching order reference, lines, and reason code.

Record your results: HTTP status, cancellation visible in the GET response (yes or no), and partial cancellation tested (yes, no, or not applicable).

Sign-off checklist

Before you go live, confirm all of the following with your ChannelEngine implementation contact:

• A unique MerchantCancellationNo is generated and stored for every cancellation, and never reused.
• Your integration polls GET /v2/cancellations/merchant regularly and uses UpdatedSince to avoid retrieving the full history on every call.
• Your integration checks IsMerchantCreator in the response and routes channel cancellations to your stop-fulfillment workflow.
• Your integration detects cancellation requests through GET /v2/orders and confirms them with POST /v2/cancellations after fulfillment is stopped.
• Merchant cancellations are submitted only for orders that have no shipment on ChannelEngine.
• The marketplace guide of each channel is checked for merchant cancellation support, and ChannelOrderSupport is checked before you submit a partial cancellation.
• If you sell on marketplaces with enforced cancellations, shipments are recorded on ChannelEngine at the moment of carrier handover and not in a delayed batch.
• Every cancellation uses the most accurate ReasonCode, and OTHER is not used as a default.
• (If applicable) Partial cancellation support is verified against the cancellation model of each channel before creating partial cancellations.

Next steps

• Merchant API: cancellations (endpoints, fields, and cancellation flows).
• ChannelEngine: cancellations (handle cancellations via the ChannelEngine web interface).