Channel API: returns

About this article

This article covers how to call GET /v2/returns/channel and POST /v2/returns/channel — which parameters to use, how to read the response, and how to handle the full returns flow.

Table of contents

About this article

Introduction

Overview

Requirements

Available API endpoints

• Endpoint: retrieve merchant returns
• Endpoint: post buyer returns

Common issues

Next steps

Introduction

When a buyer sends a product back, your channel integration needs to both communicate that return to ChannelEngine and stay in sync with how merchants are processing it. The returns endpoints give you two complementary operations: retrieving returns that ChannelEngine already knows about, and submitting new returns that originate on your platform.

Overview

Refer to the flowchart below to visualize how returns travel between your channel, ChannelEngine, and the merchant.

Requirements

• Channel API key - pass it as a request header: X-CE-KEY: {your-key}. Find it on a given channel at Setup, General, API key.
• Existing orders - returns are always linked to an order. The order referenced in a return must already exist on ChannelEngine before you can submit or retrieve returns for it.
• Pagination handling - results are capped at 100 per page. Your integration needs to handle multi-page responses. See Pagination.

Available API endpoints

The returns resource supports two operations:

• Retrieve returns: GET /v2/returns/channel
  Poll for all new and updated returns since a given date.
• Submit a return: POST /v2/returns/channel
  Notify ChannelEngine when a buyer initiates a return on your marketplace.

Endpoint: retrieve merchant returns

• Retrieve returns created by the merchant: GET /v2/returns/channel

Use this endpoint to retrieve returns registered on ChannelEngine for your channel. Call it on a regular schedule — every 15 to 30 minutes is typical — to pick up new returns and merchant status updates, then reflect those changes on your platform.

Making the request

Send a GET request to the returns endpoint, passing your Channel API key in the request header. All query parameters are optional filters:

GET https://{tenant}.channelengine.net/api/v2/returns/channel
X-CE-KEY: {your-channel-api-key}

A practical example using cURL — fetching all returns created since 1 January 2026:

curl -X GET \
  "https://demo.channelengine.net/api/v2/returns/channel?createdSince=2026-01-01T00:00:00Z&page=1" \
  -H "X-CE-KEY: your-channel-api-key" \
  -H "Accept: application/json"

Query parameters

Response structure

A successful call returns HTTP 200 with a JSON body. Returns are wrapped in the standard ChannelEngine response envelope.

Return response envelope

{
  "Content": [ /* array of return objects */ ],
  "Count": 2,          // number of returns on this page
  "TotalCount": 38,    // total matching returns across all pages
  "ItemsPerPage": 100, // maximum items per page
  "StatusCode": 200,
  "Success": true
}

An example return object from the Content array:

{
  "Id": 10042,
  "ChannelReturnNo": "RETURN-98765",
  "ChannelOrderNo": "ORDER-12345",
  "MerchantOrderNo": "MERCH-ORD-001",
  "CreatedAt": "2026-05-10T08:32:00Z",
  "UpdatedAt": "2026-05-11T14:00:00Z",
  "ReturnDate": "2026-05-13T00:00:00Z",
  "Reason": "PRODUCT_DEFECT",
  "CustomerComment": "Item arrived broken.",
  "MerchantComment": null,
  "Method": "PostNL",
  "TrackTraceNo": "3SRETURN12345",
  "TrackTraceUrl": "https://tracking.postnl.nl/track?barcode=3SRETURN12345",
  "RefundInclVat": 29.99,
  "RefundExclVat": 24.79,
  "ExtraData": {},
  "Lines": [ /* see return line fields below */ ]
}

Return fields

Return line fields

Each entry in Lines represents a single product line being returned. It includes product references, quantities, and a nested OrderLine object with the full detail of the original order line.

{
  "ChannelProductNo": "CHAN-SKU-001",
  "MerchantProductNo": "MERCH-SKU-001",
  "Quantity": 1,
  "AcceptedQuantity": 1,
  "RejectedQuantity": 0,
  "ShipmentStatus": "SHIPPED",
  "ExtraData": {},
  "OrderLine": {
    "Status": "IN_PROGRESS",
    "Quantity": 1,
    "UnitPriceInclVat": 29.99,
    "UnitVat": 5.20
  }
}

Top-level line fields

OrderLine fields

Response envelope fields

Pagination

The endpoint returns a maximum of 100 returns per page. If there are more results, request additional pages using the page parameter.

1. Make your first request without a page parameter. Defaults to page 1. Check TotalCount in the response.
2. Calculate the total number of pages. Divide TotalCount by ItemsPerPage (100) and round up. Example: 250 total returns ÷ 100 = 3 pages.
3. Request each subsequent page. Increment the page parameter with each call until all pages are retrieved.

# Page 1 — also gives you TotalCount
GET /v2/returns/channel?createdSince=2026-01-01T00:00:00Z&page=1

# Page 2
GET /v2/returns/channel?createdSince=2026-01-01T00:00:00Z&page=2

Endpoint: post buyer returns

• Send buyer returns to ChannelEngine: POST /v2/returns/channel

Use this endpoint to submit a new return to ChannelEngine. Call it when a buyer initiates a return on your marketplace and you need to notify the merchant via ChannelEngine. You must identify both the original order and the specific product lines being returned.

Making the request

Send a POST request with a JSON body. Pass your Channel API key in the request header:

curl -X POST \
  "https://demo.channelengine.net/api/v2/returns/channel" \
  -H "X-CE-KEY: your-channel-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "ChannelOrderNo": "ORDER-12345",
    "ChannelReference": "RETURN-98765",
    "Reason": "PRODUCT_DEFECT",
    "CustomerComment": "Item arrived broken.",
    "Lines": [
      {
        "ChannelProductNo": "CHAN-SKU-001",
        "Quantity": 1
      }
    ]
  }'

Request body fields

Line fields

Each object in the Lines array identifies a product line being returned and the quantity involved.

Response

A successful submission returns HTTP 200 with Success: true in the response body. No Content array is returned — only the standard envelope fields. The return is now registered on ChannelEngine and the merchant will be notified.

Common issues

Next steps

After returns handling is working, connect these related endpoints:

• GET /v2/cancellations/channel — fetch channel-initiated cancelations and update order statuses on your platform accordingly.
• GET /v2/shipments — retrieve shipments so buyers receive accurate tracking information for outbound orders.
• GET /v2/orders/new — understand how the merchant picks up orders, giving context on the full order-to-return lifecycle.
• ChannelEngine: pagination in the APIs — deeper guidance on handling large result sets efficiently across all Channel API endpoints.