Merchant API: testing orders in your sandbox

About this article

This article provides a step-by-step test script for verifying your Merchant API orders integration end-to-end before going live, covering order retrieval, data parsing, acknowledgement, channel identification, and invoice upload.

Introduction

Before connecting your integration to live orders, run through this test script in a sandbox or test environment to confirm that each part of your orders workflow behaves correctly. The five test cases cover the full order lifecycle — retrieving orders, parsing response fields, acknowledging an order, verifying channel and fulfillment behavior, and uploading an invoice. Work through them in order, as later tests build on the results of earlier ones.

For each test, record the HTTP status, the RequestId, and the LogId from the response. These identifiers allow your ChannelEngine implementation contact to locate the exact API calls on the platform side and sign off the integration before go-live. Once all five tests pass and the sign-off checklist is complete, share it with your implementation contact before switching to production.

Onboarding test script

Run through this script before going live to verify that your integration handles orders correctly end-to-end. Each test case has a clear expected result. Work through them in order — later tests depend on earlier ones succeeding. Log the RequestId and LogId from each response so you can reference specific calls when discussing results with your ChannelEngine implementation contact.

Requirements

• A ChannelEngine account with at least one channel connected.
• At least one test order visible in the ChannelEngine interface (your implementation contact can create these for you if needed).
• Your Merchant API key, available at Settings, Merchant API keys on ChannelEngine.
• A tool for making HTTP requests — Postman, curl, or your integration code.

Test 1: retrieve orders

Goal: confirm that your integration can connect to the API and retrieve orders.

1. Call GET /v2/orders/new with your API key in the request header. Expected result: HTTP 200, Success: true, Content is an array (may be empty if no test orders exist yet).
2. Verify the response envelope — confirm Count, TotalCount, and ItemsPerPage are present and numeric. Expected result: all three fields are integers. TotalCount reflects how many orders match the filter across all pages.
3. If Content is empty — call GET /v2/orders?Statuses=IN_PROGRESS&Statuses=SHIPPED&Statuses=CLOSED to check whether any orders exist in non-new statuses. Expected result: at least one order returned, confirming the API connection and authentication are working.

Record your results: 

• HTTP status:
• Success: 
• TotalCount:   
• RequestId: 

Test 2: verify order data parsing

Goal: confirm your integration correctly reads and maps the fields it needs.

1. Take the first order from the response and verify these fields are present and correctly typed in your parsed output: Id (integer, used for acknowledge call), ChannelOrderNo (string), Status (one of the known enum values), IsTest (boolean), Lines (array with at least one item), ShippingAddress.CountryIso (2-letter string), TotalInclVat (number), CurrencyCode (3-letter ISO string). Expected result: all fields parsed without errors. No fields silently dropped or cast to the wrong type.
2. Check the address format — inspect ShippingAddress. Is StreetName populated, or Line1? Both should not be populated simultaneously. Expected result: your integration selects the correct format (split fields or Line1/2/3) based on which is populated.
3. Check the delivery dates — inspect the first order line. Is LatestShipmentDate populated? Is it a valid ISO 8601 datetime string? Expected result: your integration reads this value correctly and would use it to prioritize the order in your warehouse queue.
4. Verify IsTest filtering — if any orders in the response have IsTest: true, confirm your integration would skip them rather than process them. Expected result: test orders are identified and excluded from your processing queue.

Record your results: 

• Order Id used for testing:  
• Address format present: Split fields / Line1-3 (choose one)   
• LatestShipmentDate present: Yes / No / null (choose one)   
• IsTest filtering working: Yes / No (choose one)

Test 3: acknowledge an order

Goal: confirm that your integration can acknowledge an order and set its MerchantOrderNo.

1. Select a NEW test order from Test 1. Note its Id.
2. Call POST /v2/orders/acknowledge with the Id and a test MerchantOrderNo (for example, TEST-ORD-001). Expected result: HTTP 201. The order is now acknowledged.
3. Call GET /v2/orders/new again and confirm the order no longer appears. Expected result: the acknowledged order is absent from the new orders queue.
4. Call GET /v2/orders?MerchantOrderNos=TEST-ORD-001 to retrieve the order by your reference. Expected result: the order is returned with Status: IN_PROGRESS and MerchantOrderNo: "TEST-ORD-001".
5. Attempt to acknowledge the same order a second time using the same Id. Expected result: HTTP 409 Conflict. Your integration should handle this gracefully — log the conflict and skip the order rather than crashing.

Record your results: 

• Order Id acknowledged:
• MerchantOrderNo used:
• HTTP status on acknowledge: 
• Order absent from /new after acknowledge: Yes / No (circle one)   
• 409 handled gracefully: Yes / No (choose one)   
• RequestId:

Test 4: verify channel and fulfilment behavior

Goal: confirm your integration correctly identifies the channel and handles marketplace-fulfilled lines.

1. On any order in your results, read GlobalChannelName and ChannelOrderSupport. Expected result: GlobalChannelName matches the channel you connected (for example, "bol.com"). ChannelOrderSupport is one of ORDERS, SPLIT_ORDERS, or SPLIT_ORDER_LINES. Record this value — it determines how you must structure shipment calls for this channel.
2. Inspect each order line for IsFulfillmentByMarketplace. Expected result: your integration identifies marketplace-fulfilled lines and excludes them from the warehouse pick list. If all your orders are merchant-fulfilled, this will always be false.
3. Call GET /v2/orders?ExcludeMarketplaceFulfilledOrdersAndLines=true and compare the result count to a call without this filter. Expected result: the filtered result excludes or reduces lines. If counts are identical, all your current orders are merchant-fulfilled — which is correct behavior.

Record your results: 

• GlobalChannelName: 
• ChannelOrderSupport: 
• Marketplace-fulfilled lines found: Yes / No (choose one)   
• FBM filter working correctly: Yes / No (choose one)

Test 5: invoice upload (if applicable)

Goal: confirm your integration can attach an invoice to an order. Skip this test if your channel does not require invoice upload.

1. Using the MerchantOrderNo from Test 3, call POST /v2/orders/{merchantOrderNo}/invoice-base64 with a small test PDF encoded as Base64. Set InvoiceNumber to a test value (for example, INV-TEST-001). The PDF must be under 1 MB. Expected result: HTTP 200, Success: true.
2. Verify the invoice appears in ChannelEngine — open the order in the ChannelEngine interface and check that the invoice is attached. Expected result: the invoice is visible on the order detail page.

Record your results: 

• HTTP status on invoice upload: 
• Invoice visible in CE interface: Yes / No / N/A (choose one)   
• RequestId:

Sign-off checklist

Before marking the orders integration as complete, confirm all of the following: