Merchant API: shipments

About this article

This article explains how to create, retrieve, and update shipments via the Merchant API, and how to confirm delivery. It covers the full shipment lifecycle after an order has been acknowledged. To learn how to request and download marketplace-generated shipping labels, check out Merchant API: shipping labels (last-mile delivery).

Table of contents

Introduction

Overview

Requirements

Available API endpoints

Post a shipment

Get shipments

Shipping labels

Updating a shipment

• Update tracking information
• Submit delivery state
• Upload proof of delivery
• Recommended sequence

Example requests

Common issues

FAQs

Next steps

Introduction

Once an order is acknowledged, the next step is to record its shipment on ChannelEngine. Shipment data tells the marketplace that the order is on its way and, where applicable, triggers label generation, tracking updates, and delivery confirmation.

Before creating a shipment, make sure you retrieved and acknowledged the order. The MerchantOrderNo used in that process is the order reference (or identifier) throughout this flow.

Which flow you follow depends on who provides the carrier and the label. You either ship with your own carrier and tracking details, or the marketplace generates the label for you. For marketplace-generated labels, see Merchant API: shipping labels (last-mile delivery).

Overview

Refer to the diagram below to visualize how a shipment travels between your system, ChannelEngine, and the channel.

Requirements

• A Merchant API key, available at Settings, Merchant API keys on ChannelEngine.
• An order that you retrieved and acknowledged.
• A unique MerchantShipmentNo for each shipment, which you generate in your own system.
• For marketplace-generated labels where the marketplace controls the carrier (Pattern B), completed carrier mappings on the channel. See Pattern B: delivery by marketplace.

Available API endpoints

The following endpoints cover the shipment lifecycle. To submit an order invoice that is exported with your shipment, see the article on managing orders via the Merchant API.

• Create a shipment: POST /v2/shipments
• Create a shipment and request a label (Pattern A): POST /v2/shipments/channelmethod
• Retrieve available carrier services (Pattern A): POST /v2/carriers/{merchantOrderNo}
• Retrieve shipments: GET /v2/shipments/merchant
• Update a shipment: PUT /v2/shipments/{merchantShipmentNo}
• Download a shipping label: GET /v2/orders/{merchantShipmentNo}/shippinglabel
• Retrieve the Air Waybill (AWB) number: GET /v2/orders/{merchantShipmentNo}/airwaybillno
• Submit delivery state: PUT /v2/shipments/{merchantShipmentNo}/delivery-state
• Upload proof of delivery: POST /v2/shipments/{merchantShipmentNo}/proof-of-delivery

Post a shipment

• Create a shipment: POST /v2/shipments

Use this endpoint when you are shipping an order yourself and already have, or will provide, your own carrier and tracking details. ChannelEngine records the shipment and forwards it to the marketplace. Each call creates one shipment. This endpoint does not accept an array of multiple shipments in a single request. Each shipment needs its own unique MerchantShipmentNo, which you define yourself at creation.

Request body

The API reference documents every field. The notes below explain when and why you would use each one.

For request examples, see Example requests.

Partial shipments

To partially ship an order, only include the lines and quantities shipped in the call. You can create additional shipments for the remaining lines using the same MerchantOrderNo but a different MerchantShipmentNo.

Get shipments

• Retrieve shipments: GET /v2/shipments/merchant

Use this endpoint to retrieve shipments you previously created on ChannelEngine, oldest to newest. Use it to verify data, check export status, or reconcile records with your own system.

Query parameters

Shipping labels

When your channel manages the shipping method, e.g.: Amazon, bol, or Kaufland, ChannelEngine can request a shipping label from the marketplace on your behalf. Depending on the channel, you either select the carrier service yourself (Pattern A) or the marketplace assigns it automatically (Pattern B). To learn how to request, download, and troubleshoot marketplace-generated shipping labels, and how to retrieve Air Waybill numbers, check out Merchant API: shipping labels (last-mile delivery).

Updating a shipment

Shipment details like tracking number or carrier can be added or updated after a shipment has been created. Some channels also require you to confirm the delivery status or upload a proof of delivery document.

Update tracking information

• Update a shipment: PUT /v2/shipments/{merchantShipmentNo}

Use this endpoint to add a tracking number after shipment creation or to correct carrier and tracking details already on file. Replace {merchantShipmentNo} with the shipment reference you assigned at creation.

Request body when updating a shipment

Submit delivery state

• Submit delivery state: PUT /v2/shipments/{merchantShipmentNo}/delivery-state

Use this endpoint to report the final delivery outcome. This is required by channels that need explicit merchant confirmation of delivery, typically channels that do not receive automatic tracking updates from the carrier. Check the specific marketplace guide to determine if you need to submit the delivery state.

Delivery state request body fields

Upload proof of delivery

• Upload proof of delivery: POST /v2/shipments/{merchantShipmentNo}/proof-of-delivery

If your channel or internal process requires a proof of delivery document, upload it with this endpoint. This is a multipart/form-data request. Check the specific marketplace guide to determine if you need to submit a proof of delivery.

Proof of delivery request body fields

Recommended sequence

1. Hand the parcel to the carrier and obtain a tracking number.
2. Call PUT /v2/shipments/{merchantShipmentNo} with the carrier name and tracking number, if not already included at creation time. Expect HTTP 200.
3. If required, once your tracking system or carrier confirms delivery, call PUT /v2/shipments/{merchantShipmentNo}/delivery-state with Status and DeliveredAt. Expect HTTP 201.
4. If required, upload the proof of delivery PDF via POST /v2/shipments/{merchantShipmentNo}/proof-of-delivery. Expect HTTP 201.

Example requests

For examples of marketplace-generated label requests (Pattern A and Pattern B) and Air Waybill retrieval, see Merchant API: shipping labels (last-mile delivery).

Full shipment with tracking

POST /v2/shipments

{
  "MerchantShipmentNo": "SHIP-20260817-001",
  "MerchantOrderNo": "ORD-98765",
  "Lines": [
    {
      "MerchantProductNo": "SKU-001",
      "Quantity": 2
    }
  ],
  "TrackTraceNo": "3SDESK123456789",
  "TrackTraceUrl": "https://tracking.postnl.nl/3SDESK123456789",
  "Method": "PostNL",
  "ShippedFromCountryCode": "NL",
  "IsMerchantCreator": true
}

Minimal shipment (tracking added later)

POST /v2/shipments

{
  "MerchantShipmentNo": "SHIP-20260817-002",
  "MerchantOrderNo": "ORD-98766",
  "Lines": [
    {
      "MerchantProductNo": "SKU-002",
      "Quantity": 1
    }
  ]
}

Add tracking to an existing shipment

PUT /v2/shipments/SHIP-20260817-002

{
  "Method": "DHL",
  "TrackTraceNo": "1Z999AA10123456784",
  "TrackTraceUrl": "https://www.dhl.com/en/tracking/1Z999AA10123456784"
}

Submit delivery state

PUT /v2/shipments/SHIP-20260817-001/delivery-state

{
  "Status": "DELIVERED",
  "DeliveredAt": "2026-08-19T14:32:00Z"
}

Common issues

For label-related issues, such as 404 and 410 responses, see Merchant API: shipping labels (last-mile delivery).

FAQs

Why is my shipment not processed correctly on the marketplace? 
The main reason for this is that the provided shipment information is missing or incorrect. Review the instructions in the section Create a shipment above.

Does the marketplace accept partial shipments?
Make sure to check the ChannelOrderSupport field in the response body of the retrieve orders API call, as not all marketplaces support partial shipments.

Channel order support assumes one of the following values:

• NONE - the channel does not support any orders or order follow-up actions. E.g.: Beslist does not support automated shipments or returns; therefore, it is not possible to perform any partial order actions.
• NO_SPLIT/ORDERS - the channel supports orders and follow-up actions, but these cannot be split. If an order has two order lines, both must be included in a single shipment.
• SPLIT_ORDERS - the channel supports orders and follow-up actions, but they can only be split into individual order lines. An order containing two order lines, each for one product, can be shipped in two shipments, with each shipment containing one product. However, an order line cannot be split into separate shipments. E.g.: if a buyer buys a quantity of three of the same item, all three items must be shipped at once/canceled at once.
• SPLIT_ORDER_LINES - the channel supports orders and follow-up actions, and their order lines can be split into separate shipments or further follow-up actions. E.g.: if a buyer buys a quantity of three of the same item, it is possible to ship two of the order quantities and cancel one of the quantities.

For more details on retrieving the order support level via the orders endpoint, check out Merchant API: orders.

Next steps

• Merchant API: testing shipments in your sandbox - verify your shipment integration before going live.
• Managing orders via the Merchant API - retrieve, acknowledge, and cancel orders, and submit invoices.
• Merchant API: shipping labels (last-mile delivery) - request and download marketplace-generated labels, and set up fulfillment settings on your channels.
• Managing offers via the Merchant API - keep stock and price up to date across your channels.
• Authentication and rate limits - Merchant API key setup and request throttling.