Merchant API: interpreting order lines and extra data

About this article

This article explains the fields available on orders and order lines in the Merchant API order response, including product identifiers, pricing, shipment dates, fulfillment flags, and the ExtraData key-value store for channel-specific information.

Table of contents

Introduction

Retrieve orders

Order line fields

Extra data on the order and order line 

Introduction

When you retrieve orders via GET /v2/orders or GET /v2/orders/new, each order response contains one or more arrays carrying the detailed order content. The primary array is Lines, where each object represents a single product line and includes fields for product identification, quantity, pricing, VAT, shipment deadlines, fulfillment type, and product condition. Two additional arrays — BundleOrderLines and ServiceLines — appear only in specific scenarios: bundle orders and accounts enrolled in the Service Lines Closed Beta, respectively.

Pricing fields on order lines follow the same two-set pattern as order-level financial fields. Fields without the Original prefix — such as UnitPriceInclVat and LineTotalInclVat — are in your shop's base currency after ChannelEngine currency conversion, and should be used for accounting and reconciliation. Fields with the Original prefix — such as OriginalUnitPriceInclVat and OriginalLineTotalInclVat — are in the currency the customer actually paid in, and should be used for customer-facing documents such as order confirmations and invoices.

Each order line also carries up to six shipment and delivery date fields. The most operationally important of these is LatestShipmentDate, which represents the hard warehouse deadline for that line. This article describes all order line fields in full, and covers how to work with ExtraData — a flexible key-value store that channels use to pass information that does not fit the standard order model, such as gift messages, pickup point identifiers, and customization URLs.

Retrieve orders

In the order response, your orders and order lines come with relevant information that you can use. Inspect the details of these fields for dynamic information related to the order. 

• 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 line fields

Three arrays carry the detailed order content. For most orders only Lines is populated; the other two appear in specific scenarios.

Each object in the Lines array represents a single product line on the order.

Extra data on the order and order line

ExtraData is a flexible key-value store for channel-specific information that does not have a dedicated field in the standard order model. It appears in two places: at order level (as an object) and at line level (as an array of {"Key": "...", "Value": "..."} pairs).

The most important thing to understand about ExtraData is that its contents are entirely dynamic. The keys and values depend on the channel the order came from — they are not standardized across marketplaces, and ChannelEngine does not transform or validate them. What Amazon puts in ExtraData will be completely different from what bol.com or Zalando puts there. The field can also be null or empty on orders from channels that do not provide supplementary data.

Channels use ExtraData to pass information that matters for fulfilment or compliance but does not fit the standard fields. Common examples include:

How to handle ExtraData in your integration:

• Do not hardcode assumptions about its structure. An integration that works for bol.com orders will not necessarily have the same ExtraData keys when the same merchant connects Amazon. Build your ExtraData handling to be channel-aware — check GlobalChannelName or GlobalChannelId first, then look up the relevant keys for that channel.
• Treat it as optional. If a key you expect is absent, handle null gracefully rather than throwing an error. Channels can add or remove keys over time.
• Order-level vs. line-level. Order-level ExtraData (on the order object) contains information about the order as a whole. Line-level ExtraData (inside each Lines item) contains information specific to that product line. A gift message is typically at order level; a customization URL is typically at line level.
• Log unknown keys. If you encounter an ExtraData key you do not recognize, log it rather than silently discarding it. New keys from a channel may contain data you need to act on — for example, a new regulatory compliance field.