Channel API: reports (generate and retrieve a full product feed export)

About this article

This article explains how to use the Channel API's reports endpoints to generate, track, and retrieve a full, on-demand export of a seller's products and offer mappings, and how to check for existing reports before generating a new one.

Table of contents

Introduction

Overview

Requirements

Rate limits

Available API endpoints

• Generate a report: POST /v2/reports/feed
• Check report status: GET /v2/reports/{reportId}/status
• Retrieve a report: GET /v2/reports/{reportId}
• List available reports: GET /v2/reports/channel/available

Common issues

Testing

Next steps

Introduction

If your channel relies on polling endpoints like GET /v2/products/data and GET /v2/products/offers to stay in sync, you already have a steady stream of updates from your merchants. Polling can still miss things, however — a record that slipped through during downtime, or a sync that failed silently somewhere along the way.

The reports endpoints give you a way to catch those gaps: a full, real-time export of every product and offer mapping a seller currently has, at the exact moment you request it. This article covers how to generate a report with POST /v2/reports/feed, track and retrieve it with the matching GET endpoints, and check for existing reports with GET /v2/reports/channel/available.

Available report types

Right now, the only report type available is PRODUCT_FEED, which is the product and offer mapping export described in this article. 

The reports endpoints are built to support more than one report type so that additional types can be added in the future. (As more report types are added to the API, you select between the different report types using the same reportType parameter that you use with GET /v2/reports/channel/available.)

Overview

Generating and retrieving a report follows the same pattern every time:

1. Request a new report. Call POST /v2/reports/feed. ChannelEngine responds immediately with a reportId and then starts building the report in the background — depending on how many products the seller has, this can take a moment.
2. Poll the status. Call GET /v2/reports/{reportId}/status using that reportId. The status moves from IN_PROGRESS to either DONE or FAILED.
3. Retrieve the finished report. Once the status returns DONE, call GET /v2/reports/{reportId} to get the report itself.
4. Reconcile against your own data. Compare the report contents against what you already have stored, and update anything that is missing or out of date.

Requirements

• Channel API key - the same key that you use for all other Channel API endpoints. Find it within a given channel plugin, at Setup, General, API key.
• An existing Channel API integration - the reports endpoints assume that you already have products and offers flowing through the Channel API. If you have not connected yet, see Channel API: getting started first.

Rate limits

Each of the four reports endpoints has its own rate limit of one request per minute. The limit applies per URL, individually — calling POST /v2/reports/feed does not count against your allowance for GET /v2/reports/{reportId}/status, and vice versa. Each endpoint gets its own separate one-per-minute allowance.

Available API endpoints

There are four reports endpoints in the Channel API:

1. Generate a report: POST /v2/reports/feed
   Starts generating a new product feed report and returns a reportId to track it.
2. Check report status: GET /v2/reports/{reportId}/status
   Checks whether a report is still being built, finished, or failed.
3. Retrieve a report: GET /v2/reports/{reportId}
   Retrieves the finished report by its ID.
4. List available reports: GET /v2/reports/channel/available
   Lists the reports already generated for your channel, so you can reuse one instead of generating a new one.

Generate a report: POST /v2/reports/feed

• Endpoint: POST https://{tenant}.channelengine.net/api/v2/reports/feed

Use this endpoint to start generating a new product feed report. The report contains a complete, real-time snapshot of every product the seller has, along with their offer mappings (the pricing and stock data tied to each product for your channel), exactly as they stand at the moment you make the request.

This endpoint does not take any parameters. When you call it, ChannelEngine starts processing the request in the background and responds straight away with a reportId — it does not wait for the report to finish before replying.

Making the request

Send a POST request with your Channel API key as a query parameter. No request body is needed:

POST https://{tenant}.channelengine.net/api/v2/reports/feed

A practical example using cURL:

curl -X POST \
  "https://demo.channelengine.net/api/v2/reports/feed?apikey=YOUR_API_KEY" \
  -H "accept: application/json"

Response

A successful call returns HTTP 200 with the new report's ID and its starting status:

{
  "Content": {
    "ReportId": "PF_33fc53b6-86e1-462c-851e-30265a148007",
    "ReportStatus": "IN_PROGRESS"
  },
  "IsSuccess": true,
  "TraceId": null,
  "Errors": [],
  "Validations": []
}

Check report status: GET /v2/reports/{reportId}/status

• Endpoint: GET https://{tenant}.channelengine.net/api/v2/reports/{reportId}/status

Use this endpoint to check how far along a report is. Poll it after calling POST /v2/reports/feed, until the report has finished.

Making the request

curl -X GET \
  "https://demo.channelengine.net/api/v2/reports/PF_33fc53b6-86e1-462c-851e-30265a148007/status?apikey=YOUR_API_KEY" \
  -H "accept: application/json"

Report statuses

The Status field comes back as one of four values:

Response

While the report is still being built:

{
  "Content": {
    "Status": "IN_PROGRESS",
    "ResourceUrl": null
  },
  "StatusCode": 200,
  "RequestId": null,
  "LogId": null,
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": {}
}

Once Status switches to DONE, ResourceUrl is populated with a path you can use to retrieve the report:

{
  "Content": {
    "Status": "DONE",
    "ResourceUrl": "/v2/reports/PF_33fc53b6-86e1-462c-851e-30265a148007"
  },
  "StatusCode": 200,
  "Success": true
  // remaining envelope fields omitted for brevity
}

Retrieve a report: GET /v2/reports/{reportId}

• Endpoint: GET https://{tenant}.channelengine.net/api/v2/reports/{reportId}

Use this endpoint to retrieve the finished report once its status is DONE.

Making the request

curl -X GET \
  "https://demo.channelengine.net/api/v2/reports/PF_33fc53b6-86e1-462c-851e-30265a148007?apikey=YOUR_API_KEY" \
  -H "accept: application/json"

List available reports: GET /v2/reports/channel/available

• Endpoint: GET https://{tenant}.channelengine.net/api/v2/reports/channel/available

Use this endpoint to see which reports already exist for your channel, instead of generating a new one every time. This is useful if you want to reuse a recent report rather than triggering a fresh export.

Making the request

curl -X GET \
  "https://demo.channelengine.net/api/v2/reports/channel/available?reportType=PRODUCT_FEED&apikey=YOUR_API_KEY" \
  -H "accept: application/json"

Response

{
  "Content": [
    "23-13.csv",
    "23-13.xml",
    "23.csv",
    "23.xml"
  ],
  "Count": 4,
  "TotalCount": 4,
  "ItemsPerPage": 4,
  "StatusCode": 200,
  "RequestId": null,
  "LogId": null,
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": {}
}

Common issues

Testing

Use the ChannelEngine demo environment to verify the full reports flow end-to-end before relying on it in production.

1. Generate a report. Call POST /v2/reports/feed with your test Channel API key. Confirm the response returns IsSuccess: true along with a ReportId. Note the ReportId — you'll need it for the next two steps.
2. Poll until the report is done. Call GET /v2/reports/{reportId}/status using the ReportId from step 1. Repeat once every 60 seconds, in line with the rate limit, until Status returns DONE. If Status returns FAILED instead, go back to Step 1 and generate a new report.
3. Retrieve the finished report. Call GET /v2/reports/{reportId} with the same ReportId. Confirm the response contains the product and offer mapping data you expect for your test seller.
4. Confirm the report shows up as available. Call GET /v2/reports/channel/available?reportType=PRODUCT_FEED and verify the report you just generated appears in the Content array. Try narrowing the result with createdFrom and createdTo to confirm the date filters behave as expected.
5. Test an invalid reportId. Call GET /v2/reports/{reportId}/status with a made-up or expired reportId. Confirm the response returns Status: "NOT_FOUND" rather than an error.
6. Test retrieving a report too early. Immediately after generating a new report in Step 1, call GET /v2/reports/{reportId} before its status reaches DONE. Confirm your integration handles this gracefully — for example, by always checking /status first rather than assuming the report is ready right away.

Next steps

• GET /v2/products/data and GET /v2/products/offers are your primary, day-to-day sync endpoints. Reports are a backup, not a replacement for these.
• Schedule report generation for off-peak hours, at most once a night.
• Use GET /v2/reports/channel/available before generating a new report, in case a recent one already covers what you need.