Merchant API: testing shipments in your sandbox

About this article

This article provides a step-by-step test script for verifying your Merchant API shipments integration end-to-end before going live. It covers creating a shipment, retrieving a shipping label, adding tracking, and submitting delivery state.

Table of contents

Introduction

Requirements

Test 1: create a basic shipment

Test 2: retrieve a shipping label

Test 3: add tracking to an existing shipment

Test 4: submit delivery state

Sign-off checklist

Common issues

Next steps

Introduction

Run through these tests before going live to confirm that your shipment integration works end-to-end. Work through them in order. Log your results and share them with your ChannelEngine implementation contact before sign-off.

Requirements

• A ChannelEngine test environment (e.g.: account-name-dev.channelengine.net). Request one from your implementation contact if you do not have one yet.
• At least one test order visible on ChannelEngine. Create one yourself, or your implementation contact can create these for you if needed.
• Your Merchant API key, available at Settings, Merchant API keys on ChannelEngine.
• A tool for making HTTP requests, such as Postman, curl, or your integration code.

Test 1: create a basic shipment

This test confirms that a shipment is successfully created for an acknowledged order, with tracking details included.

Retrieve a test order using GET /v2/orders/new and note its MerchantOrderNo. If you have not already done so, acknowledge it using POST /v2/orders/acknowledge. ChannelEngine requires orders to be acknowledged before a shipment can be created for them.

1. Generate a unique MerchantShipmentNo in your system and store it alongside the MerchantOrderNo.
2. Call POST /v2/shipments with the required fields plus a TrackTraceNo and Method. Expect HTTP 201. The shipment is created on ChannelEngine.
3. Verify the shipment using GET /v2/shipments/merchant. Filter by your MerchantShipmentNo and confirm the returned data matches what you submitted. Expect your shipment to appear with the correct order reference, lines, carrier, and tracking number.

Record your results:

• HTTP status of the shipment call
• Shipment visible in the GET response (yes or no)
• Tracking number correct (yes or no)

Test 2: retrieve a shipping label

This test confirms that your integration can retrieve a marketplace-generated label and handle its format. It is only required for channels that provide shipping labels via API. This test covers POST /v2/shipments but not POST /v2/shipments/channelmethod.

1. Create the shipment by calling POST /v2/shipments with the required fields and Method set to the shipment method name. Do not send tracking details. Expect HTTP 201.
2. Generate a test label for the shipment by calling POST /v2/testshippinglabel with your shipment number in the request. Expect a test label to become available for the shipment.
3. Poll GET /v2/orders/{merchantShipmentNo}/shippinglabel at a short interval until the label is available. A 404 means it is not ready yet, so keep retrying. Do not treat 404 as a permanent failure. Expect HTTP 200 with a PDF, PNG, or ZPL file.
4. Confirm the label can be printed or downloaded from your warehouse UI or WMS. Expect the label to open correctly and to be scannable.

Record your results:

• HTTP status on label retrieval
• Label format received (PDF, PNG, or ZPL)
• Label printable (yes or no)

Test 3: add tracking to an existing shipment

This test confirms that tracking details can be added or updated after shipment creation.

1. Using the shipment from Test 1 (or a new one without tracking), call PUT /v2/shipments/{merchantShipmentNo} with a Method and TrackTraceNo. Expect HTTP 200. The tracking information is updated on the shipment.
2. Verify the update using GET /v2/shipments/merchant. Filter by your MerchantShipmentNo and confirm the tracking fields reflect your update. Expect TrackTraceNo and Method to match what you submitted.

Record your results:

• HTTP status
• TrackTraceNo updated correctly (yes or no)
• Method updated correctly (yes or no)

Test 4: submit delivery state

This test confirms that your integration can report the final delivery outcome. It is only required for channels that explicitly request delivery confirmation.

1. Call PUT /v2/shipments/{merchantShipmentNo}/delivery-state with Status set to DELIVERED and a DeliveredAt timestamp. Expect HTTP 201. The delivery status is recorded against the shipment.
2. If your channel requires it, upload a proof of delivery PDF via POST /v2/shipments/{merchantShipmentNo}/proof-of-delivery. Expect HTTP 201.
3. Verify on ChannelEngine: navigate to the shipment and confirm the delivery status is displayed correctly. Expect the status to show as delivered with the correct timestamp.

Record your results:

• HTTP status of the delivery state call
• HTTP status of the proof of delivery call, if applicable
• Status visible on ChannelEngine (yes or no)

Sign-off checklist

Before going live, confirm all of the following with your ChannelEngine implementation contact.

• A unique MerchantShipmentNo is generated and stored per shipment and is never reused.
• The MerchantOrderNo is stored alongside each shipment and correctly matches the acknowledged order.
• A basic shipment is created and verified via GET /v2/shipments/merchant.
• Tracking number and carrier are submitted at creation time or added via PUT after handover to the carrier.
• (If applicable) The correct label flow (POST /v2/shipments/channelmethod or POST /v2/shipments/) is confirmed for each channel in scope. The Air Waybill number is retrieved for channels where ChannelEngine generates this. 
• (If applicable) Label retrieval uses polling or a user-triggered retry, and the integration does not treat a 404 as a permanent failure.
• (If applicable) Your warehouse or WMS can handle the label format (PDF, PNG, or ZPL) of each channel in scope.
• (If applicable) Partial shipment support is verified against the ChannelOrderSupport field for each channel before splitting orders.
• (If applicable) Delivery state is submitted via PUT /v2/shipments/{merchantShipmentNo}/delivery-state for channels that require explicit confirmation.
• (If applicable) Proof of delivery is uploaded to channels or processes that require it.

Common issues

Next steps

• Merchant API: shipments - the full reference for creating, updating, and tracking shipments.
• Merchant API: testing flow - the ChannelEngine standard testing flow per resource.