Merchant API: testing cancelations in your sandbox

About this article

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

Table of contents

About this article

Introduction

Requirements

Test 1: retrieve cancelations

Test 2: submit a cancelation

Sign-off checklist

Next steps

Introduction

Run these tests to confirm that your cancelation 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 cancelations

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

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

1. Open a test order on ChannelEngine and click Create cancelation. Select Merchant in Created by and save the cancelation.
2. Open a second test order, click Create cancelation, select Channel (Test) in Created by, and save the cancelation.
3. Call GET /v2/cancellations/merchant without filters. Expected: HTTP 200 and both cancelations in the response.
4. Call the endpoint again with UpdatedSince set to a recent timestamp. Expected: only cancelations 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 cancelation.

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

Test 2: submit a cancelation

Goal: confirm that your integration submits a merchant cancelation 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 cancelation is queued for export to the marketplace.
3. Call GET /v2/cancellations/merchant filtered by your MerchantCancellationNo. Expected: the cancelation appears with the matching order reference, lines, and reason code.

Record your results: HTTP status, cancelation visible in the GET response (yes or no), and partial cancelation 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 cancelation, 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 cancelations to your stop-fulfillment workflow.
• Your integration detects cancelation requests through GET /v2/orders and confirms them with POST /v2/cancellations after fulfillment is stopped.
• Merchant cancelations are submitted only for orders that have no shipment on ChannelEngine.
• The marketplace guide of each channel is checked for merchant cancelation support, and ChannelOrderSupport is checked before you submit a partial cancelation.
• If you sell on marketplaces with enforced cancelations, shipments are recorded on ChannelEngine at the moment of carrier handover and not in a delayed batch.
• Every cancelation uses the most accurate ReasonCode, and OTHER is not used as a default.
• (If applicable) Partial cancelation support is verified against the cancelation model of each channel before creating partial cancelations.

Next steps

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