Channel API: retrieve product content

MappedFields vs. default attributes

The product object contains two distinct sources of attribute data. Which one your integration should use depends entirely on how your channel is set up in ChannelEngine.

How MappedFields works

When your channel uses the Channel Management API, you register the attributes your marketplace requires — each with a unique system name. Sellers map their own product data to each attribute. When you call GET /v2/products/data, those mapped values come back in MappedFields keyed by your system names.

{
  "MappedFields": {
    "fabric_type": "100% organic cotton",
    "product_category_id": "apparel_tops_tshirts",
    "bullet_point_1": "Machine washable at 30°C"
  },
  "Name": "Basic Tee",
  "Description": "A comfortable everyday t-shirt."
}

In this example, use fabric_type, product_category_id, and bullet_point_1 for the marketplace listing. Name and Description are the seller's raw source data and should be ignored for this integration type.

Product object fields

Both ToBeCreated and ToBeUpdated contain the same product object shape.

ExtraData

Each product can carry a list of ExtraData entries — additional attributes that don't fit into the standard fields above, such as marketplace-specific metadata or localised content.

Response envelope fields

Pagination and sync strategy

The endpoint supports page-based pagination via the page and pageSize parameters. Use the *TotalCount fields in the response to determine whether there are more products to process.

1. Call the endpoint with a pageSize that fits your processing capacity and page=1.
   You receive the first batch of products across the three buckets.
2. Process the full batch - create listings from ToBeCreated, update from ToBeUpdated, and delist from ToBeRemoved.
3. Acknowledge the batch by calling POST /v2/products/data with the IDs you have successfully processed.
   • Acknowledged products do not appear in subsequent responses.
4. Check the TotalCount values. If the total count is higher than page × pageSize, increment page by 1 and repeat from Step 1. Continue until the response buckets are empty.

Always acknowledge products after processing them. If you do not call the acknowledgement endpoint, those products will appear in every subsequent response, causing duplicate processing.

Endpoint: acknowledging products

• Acknowledge product data changes: POST /v2/products/data

After retrieving and processing a batch of products, your integration must tell ChannelEngine which products have been successfully handled. Until a product is acknowledged, it will continue to appear in every subsequent GET /v2/products/data response.

X-CE-KEY: your-channel-api-key
Content-Type: application/json

Request body

{
  "Created": [
    {
      "Id": 1042,
      "ChannelProductNo": "MYSHOP-SKU-001"
    }
  ],
  "Updated": [
    "MYSHOP-SKU-002",
    "MYSHOP-SKU-003"
  ],
  "Removed": [
    "MYSHOP-SKU-099"
  ]
}

Request body fields

Partial acknowledgement

You do not have to acknowledge all products in a single call. If your integration processes products in smaller batches, send a separate acknowledgement for each batch as it completes. ChannelEngine will clear only the acknowledged products and keep the rest pending.

Frozen products

A product with "IsFrozen": true has been deliberately locked by the merchant. Frozen products should still be listed on your channel — they are included in ToBeCreated or ToBeUpdated just like any other product. However, your integration should not send price or stock changes for frozen products until they are unfrozen.

Treat IsFrozen as a signal to list (or keep listed) the product at its current values without overwriting them with downstream updates.

First-time onboarding

When a seller connects to your channel for the first time, your integration must perform three sequential API calls — one for each level of the product hierarchy — each followed by an acknowledgement before the next call is made. This sequencing ensures parent–child relationships are established in the correct order.

1. Grandparent products
   1. The first call returns only grandparent products — the top level of the product hierarchy. These are structural grouping containers and are not directly sold. They provide the framework that parent and child products attach to.
   2. After retrieving and processing all grandparent products (paginating as needed), acknowledge them via POST /v2/products/data before making call 2.
2. Parent products
   1. The second call returns parent products — variant group containers that sit beneath the grandparent level. Each parent references its grandparent via GrandparentChannelProductNo.
   2. Acknowledge all parent products before making call 3.
3. Child & standalone products
   1. The third call returns the sellable items: child products (variants) and standalone (single) products. Child products reference their parent via ParentChannelProductNo. These are the products that get listed as purchasable items on the marketplace.
   2. Acknowledge them to complete the initial onboarding sync.

Onboarding flow summary

1. Fetch grandparent products - call GET /v2/products/data and paginate until all grandparents are retrieved.
   • Response contains only ProductType: GRANDPARENT products in ToBeCreated.
2. Acknowledge grandparents— call POST /v2/products/data with all grandparent IDs.
   • ChannelEngine marks grandparents as processed and unlocks parent products.
3. Fetch parent products - call GET /v2/products/data again.
   • Response contains ProductType: PARENT products referencing previously acknowledged grandparents.
4. Acknowledge parents - call POST /v2/products/data with all parent IDs.
   • ChannelEngine marks parents as processed and unlocks child and standalone products.
5. Fetch child & standalone products - call GET /v2/products/data once more.
   • Response contains ProductType: CHILD and ProductType: SINGLE products ready to list.
6. Acknowledge children & standalones - call POST /v2/products/data with all remaining IDs.
   • Initial onboarding complete. Future calls return only incremental changes.

Common issues

Next steps

• Review the Acknowledging products section to make sure your integration clears processed products from the queue correctly
• Use the RequestId and LogId values from any GET response when contacting ChannelEngine Support about a specific API call
• Review the Channel API authentication documentation for guidance on API key management and rotation