Channel API: orders

About this article

This article explains how channels manage orders via ChannelEngine's Channel API. It covers creating orders from your channel and managing post-order operations, including retrieving shipments, handling merchant cancelations, and managing returns.

Table of contents

Introduction

Requirements

Available API endpoints

Request fields

• Address fields
• Order lines
• Product reference: ChannelProductNo vs MerchantProductNo
• ExtraData

Example request: create a two-line order

Response

Common issues

Testing

Next steps

Introduction

As a channel, you are responsible for creating orders on ChannelEngine when buyers complete a purchase on your marketplace. Once an order is created, the merchant fulfils it and reports back with shipment or cancelation information. ChannelEngine acts as the intermediary that synchronises this data between your marketplace and the merchant.

The order workflow via the Channel API consists of the following steps:

1. The channel creates an order on ChannelEngine with the status New via POST /v2/orders.
2. The merchant retrieves the order via GET /v2/orders/new and acknowledges it.
3. The merchant ships or cancels the order.
4. The channel retrieves the resulting shipment or cancelation data.

For a visual overview of the order workflow, refer to the flowchart below.

Requirements

• API key — A valid Channel API key. Pass it in the X-CE-KEY request header for POST operations. For GET /v2/shipments, pass the key as a URL query parameter: ?apikey={your-key}.
• Test environment — Use https://demo.channelengine.net/api during development. Switch to the production URL only when you go live.
• Products in the catalog — The products you reference in an order must already exist in ChannelEngine. See ChannelProductNo vs MerchantProductNo for how to reference them correctly.

Available API endpoints

Orders represent purchase requests made by buyers on your channel. Each order consists of one or more order lines, where each order line contains information about a purchased product and its quantity.

• Create an order: POST /v2/orders

  Use this endpoint to create a new order on ChannelEngine whenever a buyer places an order on your marketplace. You must supply a unique ChannelOrderNo to identify the order on your end. This reference is used in all subsequent API calls related to the order. The request body must include buyer information, the shipping address, and at least one order line with a valid product reference and quantity. Once submitted successfully, the order appears in the merchant's ChannelEngine account with the status New.

Request fields

The table below lists all top-level fields for POST /v2/orders.

Address fields

Both ShippingAddress and BillingAddress share the same field structure. There are two ways to submit an address: parsed (structured fields such as StreetName and HouseNr) or unstructured (Line1, Line2, Line3).

Parsed vs. Line1/Line2/Line3 fields

Fields used in both the shipping and billing addresses

Shipping address-only fields

Order lines

An order line represents a product the buyer has purchased that the merchant needs to pick, pack, and ship. Every order must contain at least one line. If a buyer orders the same product more than once, reflect this in the Quantity field of a single line — not as two separate lines.

Product reference: ChannelProductNo vs MerchantProductNo

Every order line must reference a product so ChannelEngine can match it to the correct item in the merchant's catalog. You have two options, and the right choice depends on whether your channel performs product acknowledgement.

What is product acknowledgement?

When a channel integrates with ChannelEngine, it can retrieve the merchant's product catalog via GET /v2/products/data and then call POST /v2/products/data to confirm which products it has received and processed. During this acknowledgement step, the channel assigns its own ChannelProductNo to each product. ChannelEngine then stores the mapping between the merchant's reference and the channel reference.

ExtraData

ExtraData is a free-form key-value object you can use to pass any additional information that does not fit the standard fields. It is available both at the order level and at the line level. ChannelEngine stores extra data as-is and makes it visible to the merchant.

Common uses include promotion codes, buyer loyalty tier, warehouse routing instructions, and gift messages.

Example: Extra data in an order request

"ExtraData": {
  "promotion_code": "SUMMER25",
  "buyer_tier": "GOLD",
  "gift_message": "Happy birthday!"
}

Example request: create a two-line order

This example shows a two-line order with a line-level discount, parsed address fields, and a channel that acknowledges products (using ChannelProductNo).

POST /v2/orders
X-CE-KEY: your-api-key
Content-Type: application/json

{
  "ChannelOrderNo": "MKT-98765",
  "CommercialOrderNo": "ORD-2026-98765",
  "OrderDate": "2026-05-15T09:42:00Z",
  "CurrencyCode": "EUR",
  "KeyIsMerchantProductNo": false,
  "Phone": "0612345678",
  "Email": "buyer@example.com",
  "LanguageCode": "nl",
  "PaymentMethod": "iDEAL",
  "PaymentReferenceNo": "PAY-2026-55512",
  "ShippingMethod": "PostNL",
  "ShippingServiceLevel": "STANDARD",
  "ShippingCostsInclVat": 4.99,
  "IsBusinessOrder": false,
  "ShippingAddress": {
    "FirstName": "Jan",
    "LastName": "de Vries",
    "Gender": "MALE",
    "StreetName": "Keizersgracht",
    "HouseNr": "424",
    "HouseNrAddition": "A",
    "ZipCode": "1016 GC",
    "City": "Amsterdam",
    "CountryIso": "NL",
    "AddressType": "HOME"
  },
  "BillingAddress": {
    "FirstName": "Jan",
    "LastName": "de Vries",
    "StreetName": "Keizersgracht",
    "HouseNr": "424",
    "ZipCode": "1016 GC",
    "City": "Amsterdam",
    "CountryIso": "NL"
  },
  "Lines": [
    {
      "ChannelProductNo": "CHAN-SKU-001",
      "Quantity": 2,
      "UnitPriceInclVat": 24.99,
      "FeeFixed": 0.00,
      "FeeRate": 0.10,
      "Condition": "NEW",
      "LatestDeliveryDate": "2026-05-20T23:59:00Z",
      "LatestShipmentDate": "2026-05-17T23:59:00Z",
      "OrderServiceLines": [
        {
          "Type": "DISCOUNT",
          "Description": "Promo code SUMMER25",
          "OriginalAmountInclTax": 24.99,
          "OriginalAmountTax": 4.34,
          "AmountInclTax": -2.50,
          "AmountTax": -0.43,
          "TaxRate": 21
        }
      ]
    },
    {
      "ChannelProductNo": "CHAN-SKU-002",
      "Quantity": 1,
      "UnitPriceInclVat": 49.95,
      "FeeFixed": 0.00,
      "FeeRate": 0.10,
      "Condition": "NEW",
      "LatestDeliveryDate": "2026-05-20T23:59:00Z",
      "LatestShipmentDate": "2026-05-17T23:59:00Z"
    }
  ],
  "OrderServiceLines": [
    {
      "Type": "GIFT_WRAP",
      "Description": "Gift wrapping",
      "AmountInclTax": 2.50,
      "AmountTax": 0.43,
      "TaxRate": 21
    }
  ],
  "ExtraData": {
    "promotion_code": "SUMMER25",
    "buyer_tier": "GOLD"
  }
}

Response

On success, the API returns HTTP 200 with a JSON body representing the created order. Key fields to capture from the response:

Order response fields

Common issues

Testing

1. Point your requests at the demo environment. Use https://demo.channelengine.net/api/v2/orders with your test API key.
2. Submit a test order. Send a POST with a unique ChannelOrderNo. You should receive a 200 with the created order in the response body. The order appears in the ChannelEngine web interface with status New.
3. Verify address and line data. Log in to demo.channelengine.net and check that address fields, product references, and service lines are displayed correctly on the order.
4. Simulate fulfilment. Create a shipment via the ChannelEngine web interface, then call GET /v2/shipments to verify your channel can retrieve the shipment update. This confirms the full order-to-shipment loop works end to end.
5. Test edge cases. Try multi-line orders, pickup point addresses (AddressType: PICKUP_POINT), orders using MerchantProductNo, and orders with order-level and line-level service lines.

Next steps

After orders are flowing, connect these endpoints:

• GET /v2/shipments - retrieve shipment updates and mark orders as dispatched in your marketplace.
• GET /v2/cancellations - fetch merchant-initiated cancelations and update your marketplace accordingly.
• POST /v2/returns/channel - submit buyer-initiated returns when a buyer contacts your marketplace directly.
• Rate limit headers - implement backoff using X-Rate-Limit-Remaining and X-Rate-Limit-Reset to stay within 1,000 requests per 15 minutes.