Merchant API: retrieve orders

About this article

This article describes the GET /v2/orders endpoint in the Merchant API, covering its query parameters, response envelope, order identification and status fields, business order detection, and channel identification.

Table of contents

Introduction

Retrieve orders with filters

Query parameters

Response structure

Identification and status fields

• Recognizing marketplace-fulfilled orders
• Recognizing business orders
• Identifying which channel an order came from
• Leveraging stock location data
• Retrieving order support per channel

Example response

Introduction

GET /v2/orders returns a paginated list of orders matching your filters. It gives you fine-grained control over which orders to retrieve — filtering by status, date range, channel, stock location, fulfillment type, and more. For polling-based integrations, use the FromUpdatedAtDate parameter to retrieve only orders that have changed since your last sync, keeping payloads small and processing fast.

Each order in the response includes a set of identification and status fields, two address objects (billing and shipping), a full set of financial totals in both base and original currency, and one or more arrays carrying the order line content. Orders also carry several channel identification fields — ChannelId and ChannelName are scoped to your account, while GlobalChannelId and GlobalChannelName are consistent across all merchants on ChannelEngine. For channel-specific routing logic in a multi-merchant integration, use GlobalChannelId as the reliable key.

This article covers the full set of query parameters, the response envelope structure, and the order-level fields returned by the endpoint, including guidance on recognizing business orders and identifying the source channel.

Retrieve orders with filters

GET /v2/orders returns a paginated list of orders matching your filters. Use this endpoint when you need fine-grained control over which orders to retrieve — for example, filtering by status, date range, channel, or acknowledgement state.

Query parameters

Order statuses

Below are the descriptions of each order status:

NEW — received but not yet acknowledged by the merchant
IN_PROGRESS — acknowledged and being processed
SHIPPED — shipment registered; tracking sent to channel
IN_BACKORDER — order is on hold due to insufficient stock
MANCO — partially fulfilled; some lines could not be shipped
IN_COMBI — waiting to be combined with other lines before shipping
CLOSED — order completed; no further actions needed
CANCELED — order canceled by the channel or customer
RETURNED — goods returned by the customer
REQUIRES_CORRECTION — order has a data issue that prevents processing; review required
AWAITING_PAYMENT — payment not yet confirmed. Excluded by default — add explicitly to include.

Fulfillment types

Below are the possible values for FulfillmentType:

ALL — return all orders regardless of who fulfills them
ONLY_MERCHANT — all lines fulfilled by you
ONLY_CHANNEL — all lines fulfilled by the marketplace (e.g.: Amazon FBA, bol LVB)
MIXED — some lines merchant-fulfilled, some marketplace-fulfilled
INCLUDES_MERCHANT — at least one line is merchant-fulfilled (includes ONLY_MERCHANT and MIXED)
INCLUDES_CHANNEL — at least one line is marketplace-fulfilled (includes ONLY_CHANNEL and MIXED)

Response structure

Returns a paginated collection. The top-level envelope fields are:

Identification and status fields

Each order object inside Content contains the following identification and status fields.

Recognizing marketplace-fulfilled orders

Some channels fulfill orders on the merchant's behalf — Amazon FBA, bol.com LVB (Levering via bol), and similar programs. For these orders, the marketplace stores and ships the goods, so you do not need to (and should not) process them in your own fulfilment system.

There are two levels at which marketplace fulfilment can appear:

• Order level — check FulfillmentType on the order. A value of ONLY_CHANNEL means the entire order is fulfilled by the marketplace. MIXED means some lines are marketplace-fulfilled and others are merchant-fulfilled.
• Line level — check IsFulfillmentByMarketplace on each order line. When this is true, that specific line is handled by the marketplace and you do not need to ship it.

To exclude marketplace-fulfilled orders and lines entirely from your retrieval results, set ExcludeMarketplaceFulfilledOrdersAndLines=true in your GET /v2/orders request. For mixed orders, this parameter removes the marketplace-fulfilled lines but keeps the merchant-fulfilled lines, so the order still appears in your results.

Recognizing business orders

The IsBusinessOrder boolean on the order object indicates whether ChannelEngine has classified the order as a B2B purchase. When this is true, you can expect:

• The BillingAddress.CompanyName to be populated.
• A VAT number to be present in VatNo on the order (for EU B2B transactions).
• A chamber of commerce number to be present in CompanyRegistrationNo where the channel provides it.
• Different invoicing requirements — many jurisdictions require a separate invoice format for B2B transactions, and some channels mandate invoice upload for all B2B orders.

Note that IsBusinessOrder reflects what the channel reported. Not all channels distinguish between B2B and B2C orders — in those cases this field will always be false, regardless of who actually placed the order.

Identifying which channel an order came from

Each order includes several fields for identifying its source channel. Understanding the difference between them helps when you need to apply channel-specific logic (different carriers, SLA rules, invoice formats, and so on):

Leveraging stock location data

A stock location in ChannelEngine represents a physical place from which you fulfil orders — a warehouse, a fulfilment centre, a retail store used for ship-from-store, or any other storage point. Every order line in ChannelEngine is assigned to a stock location, and the StockLocation object on each line tells you which one.

If you only operate one warehouse, stock locations are largely invisible — every line will always refer to the same single location. The field becomes important as soon as you have more than one fulfilment point.

Stock locations control three things in your integration:

• Order routing — ChannelEngine uses stock location rules to decide which warehouse should fulfil a given order line. These rules are configured in ChannelEngine and can be based on product availability, geography, or channel.
• Pick queue separation — in integrations with multiple warehouses, each warehouse typically polls orders filtered by its own StockLocationId using the StockLocationIds query parameter. This ensures each warehouse only sees and processes lines assigned to it.
• Stock level reporting — stock levels are tracked per location. When you update stock via the Offer endpoints, you push quantities at the stock location level.

To use stock locations in order processing:

1. Find your stock location IDs — on ChannelEngine, go to Settings, Stock locations. Note the ID and name of each location. Alternatively, call GET /v2/stocklocations to retrieve them via the API.
2. Filter orders by location when polling — if each warehouse runs its own integration process, pass its StockLocationId as a filter: GET /v2/orders/new?stockLocationId={id}. This scopes the result to lines assigned to that location only. Each warehouse only retrieves and processes lines it is responsible for fulfilling.
3. Read StockLocation.Name on each line — use this to route the pick within your warehouse management system, or to display the correct location label on a pick list. Lines assigned to different locations within one order can be fulfilled independently using SPLIT_ORDERS or SPLIT_ORDER_LINES shipment models (see Retrieving order support per channel).

Example — multi-warehouse polling setup:

• Warehouse A (Id: 12) polls: GET /v2/orders/new?stockLocationId=12
• Warehouse B (Id: 15) polls: GET /v2/orders/new?stockLocationId=15
• Each warehouse only sees lines assigned to it. A single order with lines split across both warehouses appears in both queues — each warehouse fulfils its own lines.

Retrieving order support per channel

The ChannelOrderSupport field on the order tells you what order model the channel uses. This affects how you should process and acknowledge the order, and how shipment confirmations need to be structured.

Example response

{
  "Content": [
    {
      "Id": 4829301,
      "ChannelName": "bol.com - NL",
      "ChannelId": 42,
      "GlobalChannelName": "bol.com",
      "GlobalChannelId": 7,
      "GlobalSalesChannelPluginInfoId": 301,
      "GlobalSalesChannelPluginInfoName": "bol.com v4",
      "ChannelOrderSupport": "SPLIT_ORDER_LINES",
      "ChannelRefundSupport": "NONE",
      "ChannelReturnSupport": {
        "SupportLevel": "NONE",
        "CreatorSupport": "ONLY_MERCHANT",
        "SupportedHandlingActions": []
      },
      "ChannelOrderNo": "CHAN-88234",
      "CommercialOrderNo": "88234",
      "MerchantOrderNo": null,
      "Status": "NEW",
      "IsBusinessOrder": false,
      "IsTest": false,
      "OrderDate": "2026-07-01T09:14:00Z",
      "CreatedAt": "2026-07-01T09:20:11Z",
      "UpdatedAt": "2026-07-01T09:20:11Z",
      "AcknowledgedDate": null,
      "ClosedAt": null,
      "MerchantComment": null,
      "Email": "customer@example.com",
      "Phone": "+31612345678",
      "LanguageCode": "nl",
      "CurrencyCode": "EUR",
      "CompanyRegistrationNo": null,
      "VatNo": null,
      "PaymentMethod": "iDEAL",
      "PaymentReferenceNo": "TXN-9182736",
      "ChannelCustomerNo": "CUST-00441",
      "BillingAddress": {
        "FirstName": "Jan",
        "LastName": "de Vries",
        "Gender": "MALE",
        "CompanyName": null,
        "AddressType": "HOME",
        "StreetName": "Keizersgracht",
        "HouseNr": "174",
        "HouseNrAddition": "A",
        "Line1": null,
        "Line2": null,
        "Line3": null,
        "ZipCode": "1016 DW",
        "City": "Amsterdam",
        "Region": null,
        "CountryIso": "NL",
        "Original": null,
        "PickupPointName": null,
        "PickupPointNumber": null
      },
      "ShippingAddress": {
        "FirstName": "Jan",
        "LastName": "de Vries",
        "Gender": "MALE",
        "CompanyName": null,
        "AddressType": "HOME",
        "StreetName": "Keizersgracht",
        "HouseNr": "174",
        "HouseNrAddition": "A",
        "Line1": null,
        "Line2": null,
        "Line3": null,
        "ZipCode": "1016 DW",
        "City": "Amsterdam",
        "Region": null,
        "CountryIso": "NL",
        "Original": null,
        "PickupPointName": null,
        "PickupPointNumber": null
      },
      "SubTotalInclVat": 49.98,
      "SubTotalVat": 8.68,
      "SubTotalExclVat": 41.30,
      "ShippingCostsInclVat": 4.95,
      "ShippingCostsVat": 0.86,
      "ShippingCostsVatRate": 0.21,
      "ShippingCostsExclVat": 4.09,
      "TotalInclVat": 54.93,
      "TotalVat": 9.54,
      "TotalExclVat": 45.39,
      "SubTotalFee": 2.50,
      "OrderFee": 0,
      "TotalFee": 2.50,
      "OriginalSubTotalInclVat": 49.98,
      "OriginalSubTotalVat": 8.68,
      "OriginalShippingCostsInclVat": 4.95,
      "OriginalTotalInclVat": 54.93,
      "OriginalTotalVat": 9.54,
      "OriginalSubTotalFee": 2.50,
      "OriginalOrderFee": 0,
      "OriginalTotalFee": 2.50,
      "Lines": [
        {
          "Id": 9102847,
          "ChannelOrderLineNo": "CHAN-88234-1",
          "ChannelProductNo": "CH-PROD-00291",
          "MerchantProductNo": "SKU-BLUE-L",
          "Gtin": "8710522914923",
          "Description": "Blue Cotton T-Shirt - Large",
          "Status": "NEW",
          "Quantity": 2,
          "CancellationRequestedQuantity": 0,
          "IsFulfillmentByMarketplace": false,
          "Condition": "NEW",
          "UnitPriceInclVat": 24.99,
          "UnitVat": 4.34,
          "UnitPriceExclVat": 20.65,
          "LineTotalInclVat": 49.98,
          "LineVat": 8.68,
          "LineTotalExclVat": 41.30,
          "OriginalUnitPriceInclVat": 24.99,
          "OriginalUnitVat": 4.34,
          "OriginalLineTotalInclVat": 49.98,
          "OriginalLineVat": 8.68,
          "OriginalFeeFixed": 0,
          "VatRate": 0.21,
          "FeeFixed": 0,
          "FeeRate": 0,
          "LatestShipmentDate": "2026-07-04T00:00:00Z",
          "ExpectedDeliveryDate": "2026-07-06T00:00:00Z",
          "LatestDeliveryDate": "2026-07-08T00:00:00Z",
          "ExactShipmentDate": null,
          "ExactDeliveryDate": null,
          "ExpectedShipmentDate": null,
          "ShippingMethod": "PostNL",
          "ShippingServiceLevel": "Standard",
          "StockLocation": { "Id": 12, "Name": "Main Warehouse" },
          "BundleProductMerchantProductNo": null,
          "BundleOrderLineId": null,
          "JurisCode": null,
          "JurisName": null,
          "ExtraData": [],
          "ServiceLines": []
        }
      ],
      "BundleOrderLines": [],
      "ServiceLines": [
        {
          "Id": 7712,
          "Type": "DISCOUNT",
          "AmountInclTax": -5.00,
          "AmountTax": -0.87,
          "TaxRate": 21,
          "OriginalAmountInclTax": -5.00,
          "OriginalAmountTax": -0.87,
          "Description": "Summer promotion discount"
        }
      ],
      "ExtraData": null
    }
  ],
  "Count": 1,
  "TotalCount": 1,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "Success": true,
  "Message": null,
  "RequestId": null,
  "LogId": null,
  "ExceptionType": null,
  "ValidationErrors": null
}