1. ChannelEngine Help Center
  2. APIs
  3. Merchant API

Articles in this section

See more

Merchant API: order line acknowledgement

  • Created
  • Updated

About this article

This article describes how to process multi-line orders via multiple systems.

Table of contents

Introduction

Requirements

How to backfill orders across multiple systems

Retrieve orders

Order acknowledgement

Example API response for a split order

Introduction

It is possible to use both a dedicated channel-fulfillment plugin, like ZEOS Fulfillment, and integrations with other warehouse management systems to fulfill multi-line orders; the channel manages order lines that it can fulfill, via the merchant plugin, and your other warehouses backfill the remaining order lines. 

However, this split-order setup is only possible if you fulfill those remaining order lines via the Merchant API. 

NB: when you use a dedicated channel-fulfillment plugin to fulfill orders, it is only possible to backfill unfulfilled order lines from other warehouses via the Merchant API.

Requirements

In order to fulfill multi-line orders via multiple connected systems, you must first enable the advanced order management feature on ChannelEngine. This way, you are able to manage multiple stock locations on ChannelEngine. For guidance, check out ChannelEngine: advanced order management [add-on].

How to backfill orders across multiple systems

  1. Retrieve orders from ChannelEngine with statuses New and In progress.
  2. Analyze New and In progress orders to check if they are split orders or merchant-fulfilled orders.
  3. Only acknowledge merchant-fulfilled orders via the Merchant API.
  4. Fulfill the unfulfilled order lines on the split orders via the Merchant API.

Retrieve orders

To retrieve orders that multiple systems fulfill, use the GET v2/orders endpoint with specific filters to fetch orders with statuses:

  • New - unacknowledged orders
  • In progress - acknowledged orders, because the channel-fulfillment plugin automatically acknowledges orders that it fulfills itself.

You need to retrieve orders in both of these statuses to view orders that the channel might have partially shipped, but still have lines remaining to be shipped by you as well. 

To retrieve orders:

  • Use the GET /v2/orders endpoint in the Merchant API, with the following parameters: 
    • statuses=NEW&statuses=IN_PROGRESS - New and In progress orders.
    • fulfillmentType=ONLY_MERCHANT - orders that are not fulfilled directly by a given marketplace but are imported to ChannelEngine for further processing by one of your connected systems.
    • channelIds=X - designate the channels whose orders you want to import by their respective IDs .
    • fromUpdatedAtDate=YYYY-MM-DD%2000:00:00 - filter on the date and time from which the given orders were updated.

Order acknowledgement

Proper order acknowledgement on ChannelEngine is critical to enable partial fulfillment via multiple connected systems. To ensure that you correctly route orders via the channel-fulfillment plugin and your own warehouse management system, use the GET v2/orders response to decide if the order is either:

  • Fully merchant-fulfilled 
  • Fully or partially fulfilled via the channel-fulfillment plugin

Then, make sure not to acknowledge the plugin-fulfilled order on ChannelEngine if any order lines are processed via the channel's dedicated channel-fulfillment plugin - even if the channel-fulfillment plugin only partially fulfills the order. 

The channel-fulfillment plugin only processes orders that are left unacknowledged on ChannelEngine. 

If any other source - including your Merchant API integration - acknowledges a channel-fulfilled order prior to ChannelEngine exporting it to the channel-fulfillment plugin, the order is not exported to the channel-fulfillment plugin. 

NB: if you prematurely acknowledge an order that can be fulfilled via the channel-fulfillment plugin, the order remains unfilled on ChannelEngine, and the related marketplace may assign penalties to your account.

Merchant-fulfilled orders

Merchant-fulfilled orders are orders that you ship yourself instead of letting them be shipped by the channel. 

Only acknowledge orders that you fully handle yourself. If you acknowledge a given order, it is not sent to the channel-fulfillment plugin.

  • In the API response, if all the order lines have the same stock location ID [StockLocation, ID], and if the ID belongs to your warehouse, you should acknowledge the order.
  • If the order lines have different stock location IDs, do not acknowledge the order.

Plugin-fulfilled orders 

Plugin-fulfilled orders are orders that you do not ship yourself but do import into your order management system for financial purposes or further processing.

Analyze these orders to check if there are order lines that you still need to fulfill from your own warehouse. 

  • Channel-fulfilled orders have order lines that have different stock location IDs from your own stock location IDs.
  • If the order lines have different stock location IDs, do not acknowledge the order.

Split orders

Split orders have order lines that have different stock location IDs.

  • If the order lines have different stock location IDs, do not acknowledge the order.
  • If one or more of the stock location IDs belong to your own warehouse, then fulfill the order lines that are linked to your warehouse.

Example API response for a split order

{
 "Content": [
   {
     "Id": 1503,
     "ChannelName": "Bol.com Plaza NL (v3)",
     "ChannelId": 6,
     "GlobalChannelName": "Bol.com Plaza NL (v3)",
     "GlobalChannelId": 567,
     "ChannelOrderSupport": "SPLIT_ORDER_LINES",
     "ChannelOrderNo": "CE-TEST-96293",
     "CommercialOrderNo": "CE-TEST-96293",
     "MerchantOrderNo": "ZEOS-1",
     "Status": "IN_PROGRESS",
     "IsBusinessOrder": false,
     "IsTest": true,
     "AcknowledgedDate": "2025-08-11T11:28:39.771072+02:00",
     "CreatedAt": "2025-08-11T11:16:42.331124+02:00",
     "UpdatedAt": "2025-08-11T11:28:40.168235+02:00",
     "ClosedAt": null,
     "MerchantComment": null,
     "BillingAddress": {
       "Line1": "Teststreet 22",
       "Line2": null,
       "Line3": null,
       "Gender": "NOT_APPLICABLE",
       "CompanyName": "",
       "FirstName": "T.",
       "LastName": "Tester",
       "StreetName": "Teststreet",
       "HouseNr": "22",
       "HouseNrAddition": "",
       "ZipCode": "1111 TT",
       "City": "Testtown",
       "Region": "",
       "CountryIso": "NL",
       "Original": "Teststreet 22"
     },
     "ShippingAddress": {
       "Line1": "Teststreet 22",
       "Line2": null,
       "Line3": null,
       "Gender": "NOT_APPLICABLE",
       "CompanyName": "",
       "FirstName": "T.",
       "LastName": "Tester",
       "StreetName": "Teststreet",
       "HouseNr": "22",
       "HouseNrAddition": "",
       "ZipCode": "1111 TT",
       "City": "Testtown",
       "Region": "",
       "CountryIso": "NL",
       "Original": "Teststreet 22"
     },
     "SubTotalInclVat": 0,
     "SubTotalVat": 0,
     "ShippingCostsInclVat": 0,
     "ShippingCostsVat": 0,
     "TotalInclVat": 0,
     "TotalVat": 0,
     "OriginalSubTotalInclVat": 0,
     "OriginalSubTotalVat": 0,
     "OriginalShippingCostsInclVat": 0,
     "OriginalShippingCostsVat": 0,
     "OriginalTotalInclVat": 0,
     "OriginalTotalVat": 0,
     "SubTotalExclVat": 0,
     "TotalExclVat": 0,
     "ShippingCostsExclVat": 0,
     "OriginalSubTotalExclVat": 0,
     "OriginalShippingCostsExclVat": 0,
     "OriginalTotalExclVat": 0,
     "OriginalSubTotalFee": 0,
     "SubTotalFee": 0,
     "OriginalOrderFee": 0,
     "OrderFee": 0,
     "OriginalTotalFee": 0,
     "TotalFee": 0,
     "Lines": [
       {
         "Id": 6897,
         "ChannelOrderLineNo": null,
         "Status": "IN_PROGRESS",
         "IsFulfillmentByMarketplace": false,
         "Gtin": null,
         "Description": "Nice Jacket 2.0 - XS",
         "StockLocation": {
           "Id": 1,
           "Name": "Default Warehouse"
         },
         "UnitVat": 0,
         "LineTotalInclVat": 0,
         "LineVat": 0,
         "OriginalUnitPriceInclVat": 0,
         "OriginalUnitVat": 0,
         "OriginalLineTotalInclVat": 0,
         "OriginalLineVat": 0,
         "OriginalFeeFixed": 0,
         "BundleProductMerchantProductNo": null,
         "BundleOrderLineId": null,
         "JurisCode": null,
         "JurisName": null,
         "VatRate": 21,
         "UnitPriceExclVat": 0,
         "LineTotalExclVat": 0,
         "OriginalUnitPriceExclVat": 0,
         "OriginalLineTotalExclVat": 0,
         "ExtraData": [],
         "ChannelProductNo": "10577",
         "MerchantProductNo": "A132206_444_100",
         "Quantity": 1,
         "CancellationRequestedQuantity": 0,
         "UnitPriceInclVat": 0,
         "FeeFixed": 0,
         "FeeRate": 0,
         "Condition": "UNKNOWN",
         "ExactDeliveryDate": null,
         "ExpectedDeliveryDate": null,
         "LatestDeliveryDate": null,
         "ExactShipmentDate": null,
         "ExpectedShipmentDate": null,
         "LatestShipmentDate": null
       },
       {
         "Id": 6898,
         "ChannelOrderLineNo": null,
         "Status": "IN_PROGRESS",
         "IsFulfillmentByMarketplace": false,
         "Gtin": null,
         "Description": "Nice Jacket 2.0 - XL",
         "StockLocation": {
           "Id": 20,
           "Name": "ZEOS TEST - Warehouse 1 - Bol"
         },
         "UnitVat": 0,
         "LineTotalInclVat": 0,
         "LineVat": 0,
         "OriginalUnitPriceInclVat": 0,
         "OriginalUnitVat": 0,
         "OriginalLineTotalInclVat": 0,
         "OriginalLineVat": 0,
         "OriginalFeeFixed": 0,
         "BundleProductMerchantProductNo": null,
         "BundleOrderLineId": null,
         "JurisCode": null,
         "JurisName": null,
         "VatRate": 21,
         "UnitPriceExclVat": 0,
         "LineTotalExclVat": 0,
         "OriginalUnitPriceExclVat": 0,
         "OriginalLineTotalExclVat": 0,
         "ExtraData": [],
         "ChannelProductNo": "10367",
         "MerchantProductNo": "A132206_444_103",
         "Quantity": 1,
         "CancellationRequestedQuantity": 0,
         "UnitPriceInclVat": 0,
         "FeeFixed": 0,
         "FeeRate": 0,
         "Condition": "UNKNOWN",
         "ExactDeliveryDate": null,
         "ExpectedDeliveryDate": null,
         "LatestDeliveryDate": null,
         "ExactShipmentDate": null,
         "ExpectedShipmentDate": null,
         "LatestShipmentDate": null
       }
     ],
     "BundleOrderLines": [],
     "Phone": "+31711000000",
     "Email": "test@channelengine.net",
     "LanguageCode": null,
     "CompanyRegistrationNo": null,
     "VatNo": null,
     "PaymentMethod": "iDEAL",
     "PaymentReferenceNo": null,
     "CurrencyCode": "EUR",
     "OrderDate": "2025-08-11T11:16:42.322316+02:00",
     "ChannelCustomerNo": null,
     "ExtraData": {
       "VAT_CALCULATION_METHOD_KEY": "FROM_PRICE_INCL"
     }
   }
 ],
 "Count": 1,
 "TotalCount": 1,
 "ItemsPerPage": 100,
 "StatusCode": 200,
 "RequestId": null,
 "LogId": null,
 "Success": true,
 "Message": null,
 "ExceptionType": null,
 "ValidationErrors": {}
}

The first order line has the StockLocation set to your Default warehouse on ChannelEngine, with ID = 1. This means that the order line should be fulfilled by you. The second order line has the StockLocation set to ZEOS TEST - Warehouse 1 - Bol, with a different stock location ID. This means that the order line is fulfilled by ZEOS via its channel-fulfillment plugin.

Please keep in mind that these names and values are examples and may differ from real-life API responses.

Related articles

Comments

0 comments

Article is closed for comments.