Channel API: shipments

About this article

This article covers how to call GET /v2/shipments via the Channel API, which filters to use, how to read the response, and how to set up a reliable polling loop.

Table of contents

About this article

Introduction

Requirements

Endpoint: retrieve merchant shipments

Making the request

Shipment query parameters

Shipment response

• Shipment response envelope
• Shipment fields
• Shipment line fields

Pagination

Polling strategy and examples

Common issues

Next steps

Introduction

When a merchant ships an order in ChannelEngine, a shipment record is created containing the carrier details, tracking number, and the order lines that have been dispatched.

As a channel, your responsibility is to poll for these shipment records and use them to update orders in your marketplace. Use shipment records to mark orders as shipped on your platform and surface tracking information to buyers.

Requirements

• Channel API key - pass it as a URL query parameter: ?apikey={your-key}. Find it on a given channel at Setup, General, API key.
• Existing shipments - orders must have been placed and shipped by the merchant before this endpoint returns data. If the result set is empty, confirm that shipments exist at Orders, Shipments.
• Pagination handling - results are capped at 100 per page. Your integration must handle multi-page responses. See Pagination.

Endpoint: retrieve merchant shipments

The shipments endpoint returns a paginated list of shipments created by merchants for your channel.

• Retrieve merchant shipments: GET /v2/shipments
  Poll for shipments created by the merchant. When the merchant ships an order in ChannelEngine, a shipment record is created containing the carrier, tracking number, and the order lines that have been dispatched. Retrieve these updates and use them to mark orders as shipped in your marketplace and give buyers accurate tracking information. Pass your API key as a URL query parameter: ?apikey={your-key}.

Making the request

Send a GET request to the shipments endpoint, passing your API key as a query parameter:

GET https://{tenant}.channelengine.net/api/v2/shipments?apikey={your-key}

A cURL example — fetching all shipments since 1 January 2024:

curl -X GET \
  "https://demo.channelengine.net/api/v2/shipments?fromDate=2024-01-01T00:00:00&apikey=YOUR_API_KEY" \
  -H "Accept: application/json"

Shipment query parameters

Shipment response

A successful call returns HTTP 200 with a JSON body. Shipments are wrapped in a standard ChannelEngine response envelope.

GET /v2/shipments?fromDate=2024-03-15T09:00:00&toDate=2024-03-15T09:30:00&apikey=YOUR_KEY

{
  "Content": [ /* array of shipment objects */ ],
  "Count": 2,
  "TotalCount": 47,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "Success": true
}

The Content array consists of one or more shipment objects, each containing shipment fields, shipment line fields, top-level line fields, and order line fields. Use TotalCount and ItemsPerPage to calculate how many pages to request. See Pagination.

Shipment response envelope

The top-level response fields appear alongside the Content array.

Shipment fields

Each object in Content represents one shipment:

{
  "ChannelOrderNo": "MKTPL-001234",
  "MerchantShipmentNo": "SHIP-00123",
  "CreatedAt": "2024-03-15T09:42:00Z",
  "UpdatedAt": "2024-03-15T10:05:00Z",
  "ShipmentDate": "2024-03-15T09:00:00Z",
  "Method": "PostNL",
  "TrackTraceNo": "3SYZXP293847123",
  "TrackTraceUrl": "https://tracking.postnl.nl/track?barcode=3SYZXP293847123",
  "ReturnTrackTraceNo": null,
  "ReturnMethod": null,
  "ShippedFromCountryCode": "NL",
  "ShippedFromStockLocationId": 42,
  "IsMerchantCreator": true,
  "AirWaybillNo": null,
  "ExtraData": {},
  "Lines": [ /* see Shipment line fields */ ]
}

Fields per shipment

Shipment line fields

Each entry in the Lines array represents a shipped product. It includes both the product references and a nested OrderLine object with the full detail of the original order line:

{
  "ChannelProductNo": "CHAN-SKU-001",
  "MerchantProductNo": "MERCH-SKU-001",
  "Quantity": 2,
  "ShipmentStatus": "SHIPPED",
  "ExtraData": {},
  "OrderLine": {
    "Status": "IN_PROGRESS",
    "IsFulfillmentByMarketplace": false,
    "Quantity": 2,
    "UnitPriceInclVat": 24.99,
    "UnitVat": 4.34,
    "LineTotalInclVat": 49.98,
    "LineVat": 8.68,
    "LatestShipmentDate": "2024-03-16T23:59:00Z",
    "ShippingMethod": "PostNL",
    "ShippingServiceLevel": "STANDARD"
  }
}

Top-level line fields

Order line fields

Pagination

The endpoint returns a maximum of 100 shipments per page. If there are more results, request additional pages using the page parameter.

1. Make your first request without a page parameter. It defaults to page 1. Check the TotalCount in the response.
2. Divide TotalCount by ItemsPerPage (100) and round up to calculate the total number of pages. For example: 250 total shipments ÷ 100 = 3 pages.
3. Request each subsequent page by incrementing the page parameter until all pages are retrieved.

# Page 1 — also tells you TotalCount
GET /v2/shipments?fromDate=2024-01-01T00:00:00&page=1&apikey=YOUR_KEY

# Page 2
GET /v2/shipments?fromDate=2024-01-01T00:00:00&page=2&apikey=YOUR_KEY

Polling strategy and examples

Poll GET /v2/shipments every 30 minutes, using fromDate and toDate to define a precise 30-minute window per call. This keeps each request lightweight and ensures no shipments are missed between runs.

1. Set fromDate to the start of your 30-minute window. On your very first run, use the timestamp from which you want to start importing. On every subsequent run, use the toDate from the previous call.
2. Set toDate to exactly 30 minutes later. Because toDate is exclusive, shipments created at exactly the toDate timestamp will be included in the next window — so there are no gaps.
3. Retrieve all pages within the window before moving on. Check TotalCount in the response. If it exceeds ItemsPerPage, request additional pages using the page parameter before advancing your window.
4. Advance the window and repeat. Use the previous toDate as the new fromDate, set a new toDate 30 minutes ahead, and run the call again.

# Window 1: 09:00 → 09:30
GET /v2/shipments?fromDate=2024-03-15T09:00:00&toDate=2024-03-15T09:30:00&page=1&apikey=YOUR_KEY

# Window 2: 09:30 → 10:00
GET /v2/shipments?fromDate=2024-03-15T09:30:00&toDate=2024-03-15T10:00:00&page=1&apikey=YOUR_KEY

Common issues

Next steps

After shipment retrieval is working, connect these:

• GET /v2/cancellations - fetch merchant-initiated cancelations and update order statuses on your channel accordingly.
• POST /v2/returns/channel - submit buyer-initiated returns when a buyer contacts your marketplace directly.
• GET /v2/orders/new - understand how the merchant picks up orders, giving context on the full order-to-shipment lifecycle.
• ChannelEngine: pagination in the APIs - deeper guidance on handling large result sets efficiently across all Channel API endpoints.