Merchant API: orders

About this article

This article explains how to retrieve and manage orders via the ChannelEngine Merchant API, covering the full order lifecycle from retrieval and acknowledgement through to invoices, documents, and interpreting fulfillment data.

Table of contents

About this article

Introduction

Overview

Order workflow

Requirements

Available API endpoints

• Endpoint: retrieve orders
• Endpoint: retrieve new orders
• Endpoint: acknowledge an order
• Endpoints: invoices
• Endpoint: generate a packing slip
• Endpoint: add an order comment
• Endpoints: order documents

Common issues

Next steps

Introduction

When a customer places an order on a connected marketplace, such as bol.com, Amazon, Zalando, or any other channel, ChannelEngine captures it and makes it available through the orders endpoints. This article explains how to retrieve those orders, acknowledge them, and work with the data they contain: addresses, order lines, pricing, delivery dates, and channel-specific behavior.

The core loop is: fetch new orders, acknowledge them with your own order reference, then fulfill and ship. Acknowledgement is the critical step that links the ChannelEngine order to your internal system. Once done, your MerchantOrderNo is the reference used in every downstream call — shipments, invoices, cancelations, and returns. Skip it, and the order stays in your GET /v2/orders/new queue indefinitely.

Beyond the basic flow, this article also covers how to interpret the order data itself: how to read addresses correctly across regions, how to identify marketplace-fulfilled lines you should not pick yourself, how to use delivery date fields to avoid late-shipment penalties, and how the channel identifier fields work when you are connected to multiple marketplaces.

Overview

Refer to the diagram below to visualize how orders flow between your connected channels, ChannelEngine, and your fulfillment system.

Orders arrive in ChannelEngine from your connected channels and are assigned an internal ChannelEngine order Id. This ID is used once — in the acknowledge call — to link the ChannelEngine order to your own order reference. After that, all API calls use your MerchantOrderNo.

You can retrieve orders using the general GET /v2/orders endpoint with a full set of filters, or use the GET /v2/orders/new shortcut to fetch only unacknowledged NEW orders. For most polling-based integrations, the /new endpoint is the right starting point.

Order workflow

The typical integration sequence for processing an order is as follows.

1. Fetch new orders — call GET /v2/orders/new to retrieve unacknowledged orders. Each order contains a ChannelEngine Id, order lines, billing and shipping addresses, financial totals, and delivery date constraints. Check IsTest: true on each order and skip test orders before processing. This endpoint returns orders with status NEW, so it catches every new order, but not necessarily every unacknowledged order: orders fulfilled externally by the channel itself, such as FBA (Fulfilled by Amazon), can arrive already in SHIPPED status without ever passing through NEW, and will not appear here.
2. Acknowledge the order — call POST /v2/orders/acknowledge with the ChannelEngine Id and your own MerchantOrderNo. The order status changes from NEW to IN_PROGRESS and is marked as acknowledged. Your MerchantOrderNo is now the reference for all downstream calls.
3. Fulfill the order — pick and pack the goods. Check LatestShipmentDate on each order line before you pick: this is your warehouse deadline. Once shipped, register the shipment via POST /v2/shipments, including the tracking number and carrier. ChannelEngine updates the order status to SHIPPED and forwards the tracking information to the channel, which notifies the customer. On some marketplaces this notification only fires once every line on the order has been shipped, so if you ship lines separately, check your channel's behavior for partial shipments.
4. Upload the invoice — if your channel or local regulations require it, upload the invoice PDF via POST /v2/orders/{merchantOrderNo}/invoice or the Base64 variant. The invoice is stored against the order and made available to the channel where applicable.

Requirements

Before making your first API call, you need the following:

• A ChannelEngine account with at least one channel connected. If you do not have a test environment yet, contact your ChannelEngine implementation contact to have one set up before you start.
• A Merchant API key generated on ChannelEngine at Settings, Merchant API keys. Click Add, give the key a name, and click Add again. Store it securely — it grants full API access to your account.
• Your base API URL constructed from your account subdomain: https://{your-subdomain}.channelengine.net/api. For example, if your ChannelEngine environment is Acme Retail, your base URL is https://acme-retail.channelengine.net/api. You can also find this URL on ChannelEngine at Settings, Merchant API keys.

Authentication

Every request to the Merchant API must include your API key. ChannelEngine supports two ways to pass it:

• Request header (recommended) — pass the key in the x-ce-key header:

x-ce-key: your-api-key-here

• Query parameter (less recommended) — append ?apikey=your-key to the URL. This works but may expose your key in third-party log files because many web servers log full URLs.

Merchant API keys give access to all Merchant API endpoints for the account they belong to. There is no endpoint-level permission scoping — a key either has full access or none. If you need to restrict access (for example, for a third-party integration), create a dedicated key and revoke it when the integration ends.

The Merchant API key is separate from the Channel API key and the Channel Management API key. Each API has its own key type — they cannot be used interchangeably.

The quickest way to verify your key and URL are correct is to make a simple authenticated request:

GET https://{your-subdomain}.channelengine.net/api/v2/orders/new
x-ce-key: your-api-key-here

A 200 response with "Success": true confirms your credentials and base URL are correct. A 401 response means either the key is wrong or you are using the wrong subdomain.

Rate limits

Every orders endpoint has an individual rate limit — a maximum number of calls allowed within a fixed time window. If you exceed the limit, ChannelEngine returns HTTP 429 Too Many Requests. The limits reset automatically when the window expires.

Every API response includes headers that tell you your current rate limit status. Read these on every response — do not wait for a 429 to discover you are approaching the limit. For details on how to find your tenant's rate limits, check out Merchant API: rate limits.

Available API endpoints

The following endpoints are available for order management via the Merchant API.

• 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.
• Acknowledge an order: POST /v2/orders/acknowledge
  Acknowledges an order to confirm you have received and imported it, and sets your MerchantOrderNo as the reference for all subsequent calls.
• Generate an invoice: GET /v2/orders/{merchantOrderNo}/invoice
  Generates a ChannelEngine sales tax invoice for the order and returns it as a PDF.
• Upload an invoice: POST /v2/orders/{merchantOrderNo}/invoice
  Uploads your own invoice PDF for an order using multipart/form-data.
• Upload an invoice (Base64): POST /v2/orders/{merchantOrderNo}/invoice-base64
  Uploads an invoice PDF encoded as a Base64 string. Use when multipart form data is not available in your environment.
• Generate a packing slip: GET /v2/orders/{merchantOrderNo}/packingslip
  Generates a ChannelEngine packing slip for the order and returns it as a PDF.
• Add an order comment: PUT /v2/orders/comment
  Adds or updates an internal merchant comment on an order. Comments are visible only within ChannelEngine.
• Retrieve order documents: GET /v2/orders/documents
  Retrieves a collection of channel-attached documents such as labels, customs forms, or compliance documents.
• Download a document file: GET /v2/orders/documents/file
  Downloads the actual file for a specific order document.
• Acknowledge a document: POST /v2/orders/documents/acknowledge
  Marks a document as received so it no longer appears in the unacknowledged documents list.

Endpoint: 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.

Check out Merchant API: retrieve orders for details on interpreting data from the general order response on:

• Recognizing marketplace-fulfilled orders - use the order response to identify if the order or some of the order lines are marketplace-fulfilled. 
• Recognizing business orders - use the order response to identify if the order is a business order.
• Identifying which channel an order came from - use the order response to identify the source channel of the order. 
• Retrieving order support per channel - the ChannelOrderSupport field on the order tells you how you should process and acknowledge the order, and how shipment confirmations need to be structured. 
• Leveraging stock location data - use the stock location in your order response to support automated order routing, prioritize fulfillment queues, and contribute to stock level reporting.

Further inspect the order response to leverage data on:

• Date fields - use the date fields to manage on-time deliveries. For details, check out Merchant API: managing on-time order delivery.
• Financial totals - for details on how to leverage finance-related data in the order response, check out Merchant API: financial totals on orders.
• Order line and extra data fields - read the details of your order line fields for dynamic information related to the order and marketplace-specific information that pertains uniquely to its orders. For details on order line and extra data fields, check out Merchant API: interpreting order lines and extra data.
• Customer details and address fields (BillingAddress and ShippingAddress) - for details on using your order response's address fields, check out Merchant API: customer details and addresses on orders.
• Service lines - some merchants receive specialized financial fields on orders, called service lines. For details, check out Merchant API: orders (service lines) [beta].

Endpoint: retrieve new orders

GET /v2/orders/new is a shortcut endpoint that returns only orders with status NEW — those that have not yet been acknowledged. This is the recommended starting point for most polling-based integrations.

The response structure is identical to GET /v2/orders.

Endpoint: acknowledge an order

POST /v2/orders/acknowledge acknowledges an order to confirm you have received and imported it. Acknowledgement sets your own MerchantOrderNo as the reference for all subsequent API calls on this order. Until an order is acknowledged, it continues to appear in GET /v2/orders/new.

Request body fields:

{
  "OrderId": 4829301,
  "MerchantOrderNo": "ORD-2026-00412"
}

Response codes:

Endpoints: generate and upload invoices

You can generate a ChannelEngine-managed invoice for an order, or upload your own. For details, check out Merchant API: generate or upload an order invoice (sent with shipments).

Endpoint: generate a packing slip

GET /v2/orders/{merchantOrderNo}/packingslip generates a ChannelEngine packing slip for the order and returns it as a PDF.

Endpoint: add an order comment

PUT /v2/orders/comment adds or updates a merchant comment on an order. Comments are internal — they are visible in ChannelEngine but are not sent to the channel or the customer. Identify the order by either OrderId or MerchantOrderNo; at least one is required.

Endpoints: retrieve and acknowledge order documents

Some channels attach documents to orders — such as labels, customs forms, or compliance documents. For details on how to download and acknowledge order documents, check out Merchant API: retrieve order documents.

Common issues

Next steps

• Before processing real orders, complete ChannelEngine's onboarding test script in your test environment. Check out Merchant API: testing orders in your sandbox.
• Once orders are acknowledged, create shipments via POST /v2/shipments to update the order status and push tracking information to the channel.
• If customers request cancelations, handle them via the cancelations endpoints (POST /v2/cancellations) rather than ignoring the order.
• For channels that require invoice upload, automate this step as part of your fulfillment flow so invoices are attached before shipment confirmation.
• Include RequestId and LogId from any response when contacting ChannelEngine Support about a specific API call.