Merchant API: orders
About this article
This article describes how to manage orders via the Merchant API.
Table of contents
Introduction
There are two main reasons why you might need to retrieve orders from ChannelEngine:
- To fulfill the order yourself, in which case your WMS, OMS, or ERP system retrieves merchant-fulfilled orders from ChannelEngine.
- For reporting or accounting purposes, in which case you retrieve a list of marketplace-fulfilled orders that are handled by the marketplace.
Available API endpoints
Retrieve orders
Retrieve both merchant-fulfilled and marketplace-fulfilled orders via the Merchant API. Merchant-fulfilled orders are orders that are handled by you. Marketplace-fulfilled orders are orders handled by the marketplace.
Retrieve merchant-fulfilled orders:
GET /v2/orders/new
ChannelEngine always imports merchant-fulfilled orders with the status New. To filter orders by warehouse location, indicate the stockLocationId parameter. For details on managing stock locations on ChannelEngine, check out ChannelEngine: advanced order management [add-on].
Retrieve marketplace-fulfilled orders:
GET /v2/orders
You can retrieve marketplace-fulfilled orders for administrative and reconciliation purposes. A marketplace-fulfilled order is typically released by the marketplace once it is shipped, and the order appears on ChannelEngine with the order status Shipped. To filter by the date on which the order was created on ChannelEngine, apply date and time filters with the fromCreatedAtDate and toCreatedAtDate parameters.
This is because the order handling time of a marketplace might vary per product, and the channel-fulfilled order might be imported into ChannelEngine only several days after it was created on the marketplace.
Mixed orders contain one or more merchant-fulfilled order lines and one or more marketplace-fulfilled order lines.
Retrieve mixed orders:
GET /v2/orders
First, ChannelEngine imports the merchant-fulfilled order lines, and the full order appears with status New. Process merchant-fulfilled order lines in the same way that you process full merchant-fulfilled orders.
Next, the marketplace ships the marketplace-fulfilled order lines. Then, ChannelEngine add these order lines to the existing order with the status Shipped on each respective order line. To retrieve the marketplace-fulfilled order lines of mixed orders, filter with the parameter fromCreatedAtDate and fulfillmentType = MIXED. This filter returns mixed orders containing both merchant-fulfilled and marketplace-fulfilled order lines. To filter based on the date when the order was updated, use the parameters fromUpdatedAtDate and toUpdatedAtDate.
Acknowledge orders
Some endpoints require an acknowledgement for the order status to be changed, and to make follow-up actions possible. The most important endpoint is GET /v2/orders/new. If an order is not acknowledged, it remains in status New and is returned indefinitely as a new order.
Acknowledge new orders:
POST /v2/orders/acknowledge
After retrieving new merchant-fulfilled orders or order lines, you have to acknowledge them by linking your unique MerchantOrderNo; to the ChannelEngine OrderId of the order.
After an order is acknowledged, its status automatically changes from New to In progress. The next time you call the GET /v2/orders/new endpoint, the already acknowledged orders are not included in the list.
It is also possible to acknowledge marketplace-fulfilled orders. However, in this case, the order status does not change. Acknowledging marketplace-fulfilled orders is useful to provide you with better filtering options and a clearer overview of orders.
Upload merchant invoices
Some marketplaces, such as Mirakl-based marketplaces and Amazon, give you the option to choose how you want to handle invoices for orders: get them automatically generated by ChannelEngine or upload them yourself. If you choose to upload invoices yourself, you can do so via the Merchant API.
Upload invoices for orders:
POST /v2/orders/{merchantOrderNo}/invoice
Use this endpoint to upload merchant invoices for orders. Provide a unique Merchant order number for the order and include the invoice in PDF format in the request body.
If your merchant system does not support PDF invoices and can only process text, you can use Base64 encoding for your order invoices. To provide the invoice in the Base64 format to ChannelEngine, send a request to the POST /v2/orders/{merchantOrderNo}/invoice-base64 endpoint – including the invoice content and invoice number in the body of the request.
Download documents
Download order documents, if documents are available, using the following endpoint:
GET /v2/orders/documents
Refer to the respective channel guide to find out which endpoint to use to retrieve and download your shipping labels, as the endpoint used for downloading shipping labels can vary from channel to channel.
Order troubleshooting
If you cannot process an order, there are two possible reasons:
- The input is not validated correctly (e.g.: an address field your system can not handle or an SKU that is unknown). In this case, do not acknowledge the order – but correct the input causing the error. In the case of addresses or other buyer information, this correction can either be done on the ChannelEngine web interface or via ChannelEngine's Support team. If it is an incorrect SKU (such as an old listing remaining on a marketplace) of a known product, contact ChannelEngine's Support, as this can only be corrected in the database.
- The product is not available (e.g.: the SKU sold no longer has any stock, so the order cannot be fulfilled). This depends on your logistical setup and how fast backorders can be delivered. Some ChannelEngine customers auto-cancel orders in this case.
To automatically cancel orders:
- Acknowledge an order with a unique Merchant order number. This can also be a unique placeholder if the underlying system can only provide IDs for accepted orders.
- Submit a cancelation for the order via a
POST /v2/cancellationscall and provide a Merchant order number.
In both scenarios, it is crucial to act on the order.
Order details response
In the GET /orders response, the parameters that start with Original contain the values in the original currency of the marketplace. The parameters that do not start with Original contain the values converted into the currency selected for the tenant.
Example: order currency is different from tenant currency
E.g.: below is an example of an order created on Amazon Poland. The tenant is configured in euros, but the order was originally placed in the Polish złoty.
Example: an order that should ship to a pick-up point
{
"Content": [
{
"Id": 2004,
"ChannelName": "TestChannel 1",
"ChannelId": 1,
"GlobalChannelName": "Test Channel",
"GlobalChannelId": 950,
"GlobalSalesChannelPluginInfoId": "950",
"GlobalSalesChannelPluginInfoName": "Sales channel",
"ChannelOrderSupport": "SPLIT_ORDER_LINES",
"ChannelOrderNo": "CE-TEST-54740",
"CommercialOrderNo": "CE-TEST-54740",
"MerchantOrderNo": null,
"Status": "NEW",
"IsBusinessOrder": false,
"IsTest": true,
"AcknowledgedDate": null,
"CreatedAt": "2025-08-08T17:34:55.6803869+02:00",
"UpdatedAt": "2025-08-08T17:34:55.6803869+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,
"PickupPointNumber": "21342",
"PickupPointName": "First Point",
"AddressType": "PICKUP_POINT",
"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": 130.00,
"SubTotalVat": 18.89,
"ShippingCostsInclVat": 0.00,
"ShippingCostsVat": 0.00,
"TotalInclVat": 130.00,
"TotalVat": 18.89,
"OriginalSubTotalInclVat": 130.00,
"OriginalSubTotalVat": 18.89,
"OriginalShippingCostsInclVat": 0.00,
"OriginalShippingCostsVat": 0.00,
"OriginalTotalInclVat": 130.00,
"OriginalTotalVat": 18.89,
"SubTotalExclVat": 111.11,
"TotalExclVat": 111.11,
"ShippingCostsExclVat": 0.00,
"OriginalSubTotalExclVat": 111.11,
"OriginalShippingCostsExclVat": 0.00,
"OriginalTotalExclVat": 111.11,
"OriginalSubTotalFee": 0.00,
"SubTotalFee": 0.00,
"OriginalOrderFee": 0.00,
"OrderFee": 0.00,
"OriginalTotalFee": 0.00,
"TotalFee": 0.00,
"Lines": [
{
"Id": 7004,
"ChannelOrderLineNo": null,
"Status": "NEW",
"IsFulfillmentByMarketplace": false,
"Gtin": null,
"Description": "Easter egg",
"ShippingMethod": "testMethod2",
"ShippingServiceLevel": "testLevel2",
"StockLocation": {
"Id": 1,
"Name": "Default Warehouse"
},
"UnitVat": 2.91,
"LineTotalInclVat": 40.00,
"LineVat": 5.81,
"OriginalUnitPriceInclVat": 20.00,
"OriginalUnitVat": 2.91,
"OriginalLineTotalInclVat": 40.00,
"OriginalLineVat": 5.81,
"OriginalFeeFixed": 0.00,
"BundleProductMerchantProductNo": null,
"BundleOrderLineId": null,
"JurisCode": null,
"JurisName": null,
"VatRate": 17.00,
"UnitPriceExclVat": 17.09,
"LineTotalExclVat": 34.19,
"OriginalUnitPriceExclVat": 17.09,
"OriginalLineTotalExclVat": 34.19,
"ExtraData": [],
"ChannelProductNo": "10465",
"MerchantProductNo": "EasterEgg1",
"Quantity": 2,
"CancellationRequestedQuantity": 1,
"UnitPriceInclVat": 20.00,
"FeeFixed": 0.00,
"FeeRate": 0.00,
"Condition": "UNKNOWN",
"ExactDeliveryDate": null,
"ExpectedDeliveryDate": null,
"LatestDeliveryDate": null,
"ExactShipmentDate": null,
"ExpectedShipmentDate": null,
"LatestShipmentDate": null
},
{
"Id": 7005,
"ChannelOrderLineNo": null,
"Status": "NEW",
"IsFulfillmentByMarketplace": false,
"Gtin": null,
"Description": "TestConfigurableProduct-red",
"ShippingMethod": "testMethod2",
"ShippingServiceLevel": "testLevel2",
"StockLocation": {
"Id": 1,
"Name": "Default Warehouse"
},
"UnitVat": 13.08,
"LineTotalInclVat": 90.00,
"LineVat": 13.08,
"OriginalUnitPriceInclVat": 90.00,
"OriginalUnitVat": 13.08,
"OriginalLineTotalInclVat": 90.00,
"OriginalLineVat": 13.08,
"OriginalFeeFixed": 0.00,
"BundleProductMerchantProductNo": null,
"BundleOrderLineId": null,
"JurisCode": null,
"JurisName": null,
"VatRate": 17.00,
"UnitPriceExclVat": 76.92,
"LineTotalExclVat": 76.92,
"OriginalUnitPriceExclVat": 76.92,
"OriginalLineTotalExclVat": 76.92,
"ExtraData": [],
"ChannelProductNo": "10126",
"MerchantProductNo": "TestConfigurableProduct-red",
"Quantity": 1,
"CancellationRequestedQuantity": 0,
"UnitPriceInclVat": 90.00,
"FeeFixed": 0.00,
"FeeRate": 0.00,
"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-08T17:34:55.0401797+02:00",
"ChannelCustomerNo": null,
"ExtraData": {
"VAT_CALCULATION_METHOD_KEY": "FROM_PRICE_INCL"
}
}
]
} Order line support
Whether an order can be split into multiple shipments depends on the marketplace. To find out what order processing support the marketplace provides, call GET /v2/orders or GET /v2/orders/new and check the response field ChannelOrderSupport.
Channel order support assumes one of the following values:
- 0 (NONE) - the channel does not support any orders or order follow-up actions. E.g.: Beslist does not support automated shipments or returns; therefore, it is not possible to perform any partial order actions.
- 1 (NO_SPLIT/ORDERS) - the channel supports orders and follow-up actions, but these cannot be split. If an order has two order lines, both must be included in a single shipment.
- 2 (SPLIT_ORDERS) - the channel supports orders and follow-up actions, but they can only be split into individual order lines. An order containing two order lines, each for one product, can be shipped in two shipments, with each shipment containing one product. However, an order line cannot be split into separate shipments. E.g.: if a buyer buys a quantity of three of the same item, all three items must be shipped at once/canceled at once.
- 3 (SPLIT_ORDER_LINES) - the channel supports orders and follow-up actions, and their order lines can be split into separate shipments or further follow-up actions. E.g.: if a buyer buys a quantity of three of the same item, it is possible to ship two of the order quantities and cancel one of the quantities.
One of the most common reasons for 4xx errors is that shipment or cancelation lines contain an invalid shipped or canceled quantity. The quantity shipped must match the quantity that the channel expects to ship.
Example: channel expects one shipment on full order line
{
"StatusCode":400,
"LogId":null,
"Success":false,
"Message":"Channel requires one shipment line per order line. Incomplete shipment line for order line id 2: expected quantity 3, received 1","ValidationErrors":{}
}To check whether an order or order line can be split, check the ChannelOrderSupport field.
Example: The value of the ChannelOrderSupport field shows split order support.
"Id": 86351, "ChannelName": "bol.com Plaza NL (v3)", "ChannelId": 6, "GlobalChannelName": "bol.com Plaza NL (v3)", "GlobalChannelId": 76, "GlobalSalesChannelPluginInfoId": 76, "GlobalSalesChannelPluginInfoName": "bol.com Plaza NL (v3)", "ChannelOrderSupport": "SPLIT_ORDERS", "ChannelOrderNo": "1107022893"
The example above shows an order from bol, which only allows SPLIT_ORDERS. The order lines can be shipped in separate shipments, but the order lines themselves can not be split into separate shipments.
Order extra data
Channels typically send extra data with the full order and/or with given order lines, indicating tax data, shipping types, and discounts, among other items. To retrieve the extra data fields that the channel sends with its orders, use GET /orders/new and look at the following data arrays in the response:
order_ExtraData[]for extra/additional data on the order level.order_lines[].order_line_ExtraData[]for extra/additional data on the order-line level.
Using order extra data in your integration with ChannelEngine
It is recommended to treat additional fields as dynamic and not as a fixed schema that is copied from the given channel's marketplace guide.
For each extra data field, note:
key– the key that you should rely on in your integration.value– the actual data (string, enum, array, etc.).
Build a list of unique key values that you see across all sampled orders. Because the marketplace operator can change additional fields at any time:
Re‑check periodically (e.g.: during onboarding and when adding new features).
If you depend heavily on a specific field for critical business logic, align with the marketplace operator so they know not to change or remove the field without warning. (If the given marketplace is based on Mirakl, align directly with the Mirakl administrator.
Never assume an additional field is always there; check for its presence with the Merchant API before using the field in your integration.
Test orders
While setting up your API connection, it can be useful to test out your requests with test orders. You can create multiple test orders on the ChannelEngine web interface and via the Merchant API. For guidance on creating test orders to test your requests, check out ChannelEngine: how to create test orders, Merchant API: how to create test orders, and Merchant API: testing flow.
Comments
0 comments
Article is closed for comments.