Channel API: retrieve product offers

About this article

This article explains how the GET /v2/products/offers endpoint works via the Channel API, what each field in the response means, how to handle pagination, and how to acknowledge retrieved offers.

Table of contents

About this article

Introduction

Overview

Requirements

Available API endpoints

• Endpoint: retrieve product offers
• Endpoint: acknowledge product offers

Common issues

Next steps

Introduction

When building a channel integration, you need a reliable way to fetch the current operational data — pricing, stock, and fulfilment attributes — for every product a merchant has made available to your channel. The GET /v2/products/offers endpoint provides exactly that: a paginated list of product offers containing the transactional values your channel needs to display and enforce at any given moment.

A product offer contains the transactional attributes of a listing: price, stock level, shipping time, discount pricing, and similar fulfilment-related data. This is distinct from product content (titles, descriptions, images, and other catalogue attributes), which is handled by the GET /v2/products/data endpoint.

After retrieving offers, your integration must acknowledge them. This tells ChannelEngine that your channel has successfully processed the batch. Until offers are acknowledged, ChannelEngine will continue to return them on subsequent GET calls.

Overview

Refer to the flowchart below to visualise how product offer data travels between your channel, ChannelEngine, and the merchant.

Requirements

Before calling this endpoint, make sure you have the following in place:

• A valid Channel API key issued for your ChannelEngine integration.
• Your integration registered as a channel on ChannelEngine. A Merchant API key will not work with this endpoint.
• At least one merchant connected to your channel with products in Active status.
• Offer fields configured for your channel via the Channel Management API. These determine which transactional attributes appear in MappedFields.

Available API endpoints

The product offers workflow uses two endpoints: one to retrieve current offer data and one to acknowledge that your channel has processed it.

• Retrieve product offers: GET /v2/products/offers
  Returns a paginated list of product offers for your channel, including price, stock, and any additional transactional attributes defined in your channel configuration.
• Acknowledge product offers: POST /v2/products/offers
  Call this endpoint after successfully processing a batch of offers. Pass the ChannelProductNo values of all processed offers in the request body.

Endpoint: retrieve product offers

Use this endpoint to retrieve all current product offers available to your channel.

GET /v2/products/offers

Authenticate by passing your Channel API key in the request header:

X-CE-KEY: your-channel-api-key

Query parameters

All parameters are optional. When none are provided, the first page of all available offers is returned.

Making the request

1. Open your HTTP client - create a new GET request in Postman, curl, or your preferred tool.
2. Set the request URL - use your tenant's base URL followed by the endpoint path: https://<your-tenant>.channelengine.net/api/v2/products/offers
   Replace <your-tenant> with your ChannelEngine tenant name, e.g. demo.
3. Add the authentication header - X-CE-KEY: <your-channel-api-key>
4. Optionally specify a page - append ?page=1 to request a specific page of results.
   If omitted, the first page is returned by default.
5. Send the request - a successful call returns HTTP 200 with a JSON body.
6. Acknowledge the offers - after processing the returned offers, call POST /v2/products/offers to confirm receipt. See the section on acknowledging offers below.

Example request

curl -X GET \
  "https://demo.channelengine.net/api/v2/products/offers?page=1" \
  -H "X-CE-KEY: your-channel-api-key" \
  -H "Accept: application/json"

Response structure

A successful request returns HTTP 200 with a JSON body. The response contains a Content array of product offer objects, plus a set of envelope fields for pagination, status, and diagnostics.

{
  "Content": [
    {
      "ChannelProductNo": "CH-98765",
      "MerchantProductNo": "SKU-00123",
      "Price": 29.99,
      "Stock": 142,
      "MappedFields": {
        "ShippingTime": "2-3 business days",   // system name → seller's value
        "DiscountPrice": "24.99",
        "ShippingCost": "3.95"
      }
    }
  ],
  "Count": 1,
  "TotalCount": 543,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "RequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "LogId": "log-abc123",
  "Success": true,
  "Message": null,
  "ExceptionType": null,
  "ValidationErrors": {}
}

Offer fields

Each object in the Content array represents a single product offer.

MappedFields

MappedFields contains the offer fields you have defined for your channel via the Channel Management API. These are transactional attributes that go beyond the standard Price and Stock fields — typical examples include shipping time, discount price, shipping cost, or fulfilment method.

Each key is the system name of an offer field as configured in your channel definition. Each value is the corresponding data supplied by the seller for that product.

"MappedFields": {
  "ShippingTime": "2-3 business days",   // system name: "ShippingTime"
  "DiscountPrice": "24.99",               // system name: "DiscountPrice"
  "ShippingCost": "3.95"                  // system name: "ShippingCost"
}

The system name you define in the Channel Management API is the exact string that appears as the key in MappedFields. Choose system names that are stable and machine-readable (e.g.: ShippingTime, DiscountPrice, ShippingCost), since your integration will reference them directly.

How MappedFields are populated

1. You define offer fields in the Channel Management API - each field has a system name (e.g. ShippingTime, DiscountPrice) that becomes the key in MappedFields.
2. Merchants map their product attributes to your fields - from their ChannelEngine account, merchants map values from their catalogue to each of your defined offer fields.
3. The merchant's values are returned in MappedFields - when you call GET /v2/products/offers, each offer includes the merchant's mapped values keyed by your system names.

Response envelope

Every response includes a set of top-level fields for pagination, status, and diagnostics.

Pagination

Results are returned in pages. Use the envelope metadata to navigate through all available offers without missing any.

1. Make your first request. Call the endpoint without a page parameter, or with page=1. Note the TotalCount and ItemsPerPage values in the response. For example: TotalCount: 543 and ItemsPerPage: 100 means six pages of results.
2. Calculate the total page count. Divide TotalCount by ItemsPerPage and round up: ceil(TotalCount / ItemsPerPage).
3. Increment through pages. Repeat the request with page=2, page=3, and so on until all pages have been retrieved.
4. Stop when complete. Stop when Count is 0 or the current page number exceeds the total page count calculated in step 2.
5. Acknowledge all retrieved offers. Once you have processed all pages, call POST /v2/products/offers to acknowledge the batch. See Endpoint: acknowledge product offers below.

Endpoint: acknowledge product offers

After retrieving and processing a batch of offers, your integration must acknowledge them. This tells ChannelEngine that your channel has successfully received the data. Until offers are acknowledged, ChannelEngine will continue to return them on subsequent GET calls.

POST /v2/products/offers

Send the ChannelProductNo values of all processed offers as a JSON array in the request body:

POST /v2/products/offers
X-CE-KEY: your-channel-api-key
Content-Type: application/json

[
  "CH-98765",
  "CH-98766",
  "CH-98767"
]

You can acknowledge offers per page rather than waiting until all pages are complete. Acknowledging each page immediately after processing it keeps the queue clear and reduces the risk of reprocessing large batches on failure.

Common issues

If you receive an unexpected error, note the RequestId and LogId values from the response and include them when contacting ChannelEngine Support. These references allow the support team to trace your exact request in the system.

Next steps

• Review the Channel Management API documentation to learn how to define and manage offer fields — these control which transactional attributes appear in MappedFields.
• Use GET /v2/products/data to retrieve product content — titles, descriptions, and images — for creating and updating listings on your channel.
• Include the RequestId and LogId values from any response when contacting ChannelEngine Support about a specific API call.
• You can test API calls against the ChannelEngine demo environment at demo.channelengine.net before pointing your integration at a production tenant.