Merchant API: managing on-time order delivery

About this article

This article explains how to retrieve orders via the Merchant API, what each order-level and order line-level date field means, and how to use shipment date and delivery date fields to meet channel SLAs and avoid late shipment penalties.

Table of contents

Introduction

Retrieve orders

Order-level date fields

Managing on-time delivery using order line date fields

Introduction

When a customer places an order on a channel, ChannelEngine receives it and makes it available to you via the Merchant API. Two endpoints cover order retrieval: GET /v2/orders for filtered, paginated queries and GET /v2/orders/new for unacknowledged new orders. For most polling-based integrations, GET /v2/orders/new is the recommended starting point.

Each order carries a set of order-level date fields — such as CreatedAt, UpdatedAt, and AcknowledgedDate — that track the order's lifecycle in ChannelEngine. At the order line level, up to six shipment and delivery date fields define the window within which you must pick, pack, and hand the parcel to your carrier. Channels use these fields to enforce their SLAs, and missing them can result in penalties, automatic cancelations, or late delivery strikes.

This article walks through both endpoint options, explains each date field, and provides guidance on how to prioritize the shipment and delivery fields to keep your fulfillment operations on time.

Retrieve orders

• Retrieve orders: GET /v2/orders
  Returns a paginated list of orders matching your filters. Use this endpoint when you need fine-grained control — for example, filtering by status, date range, channel, or acknowledgement state.
• Retrieve new orders: GET /v2/orders/new
  Returns only orders with status NEW that have not yet been acknowledged. The recommended starting point for most polling-based integrations.

Order-level date fields

Once you retrieve your orders, inspect your order-level and order line-level date fields. The following fields appear on the order level:

Managing on-time delivery using order line date fields

Each order line carries up to six date fields that together define your shipment and delivery window. These are set by the channel based on the customer's chosen service level, the channel's SLA, and the carrier method. Getting these right is the difference between a timely delivery and a late shipment penalty or cancelation.

The fields come in three pairs — one pair for shipment (when you hand the parcel to the carrier) and one pair for delivery (when the customer receives it). Within each pair there are three variants:

Apply the following priority order when deciding when to ship:

1. Check ExactShipmentDate first. If it is populated, this is a hard constraint from the channel. Ship on this date only — not before, not after. Applies to channels with strict same-day or scheduled delivery programs.
2. If ExactShipmentDate is null, use LatestShipmentDate as your deadline. This is the most operationally important field for most integrations. Build your pick-and-pack SLA around this date — if you cannot ship by this date, cancel the line rather than ship late. Most marketplace channels (bol.com, Amazon, Zalando) set this field and penalize late shipments.
3. Use ExpectedDeliveryDate for customer communication and carrier selection. Choose a carrier and service level that can reliably meet this date given your LatestShipmentDate. If the gap between LatestShipmentDate and ExpectedDeliveryDate is very tight, you may need an express carrier.
4. If LatestDeliveryDate is populated, verify your carrier can meet it. This is the SLA ceiling — missing it may trigger a channel penalty, a customer refund, or an automatic return. Flag orders where LatestDeliveryDate is less than two days away and no shipment has been created yet.

Example: reading a bol order line

• LatestShipmentDate: "2026-07-04T23:00:00Z" — must be handed to the carrier by 11pm on 4 July.
• ExpectedDeliveryDate: "2026-07-06T00:00:00Z" — customer was promised delivery by 6 July.
• LatestDeliveryDate: "2026-07-08T00:00:00Z" — absolute SLA deadline; missing this triggers a late delivery strike.
• ExactShipmentDate: null — no exact shipment date required; ship any time before the latest date.