ChannelEngine: connect to the Channel API

About this article

This article describes the Channel API, its prerequisites, usage, rate limits, and more.

Table of contents

Introduction

Using the API

Product, pricing and stock information

Orders

Shipments

Returns

Rate limits

Video

Questions?

Introduction

To connect a new marketplace or ecommerce platform as a sales or data channel to ChannelEngine, you can either use the Channel API or a combination of the Channel API and data feeds (be them XML- or CSV-based).

For more information on the Channel API, refer to one of the following links:

• API reference (OpenAPI/Swagger)
• Channels: data flow
• REST API: client libraries for channels

Using the API

When operating the Channel API, make sure to use your personal subdomain .channelengine.net (e.g.: sustainable-suits.channelengine.net).

The API key to access the Channel API for your specific channel can be found under the Setup tab of the channel settings.

Note that this key is different for each individual channel, and can only access the data for that specific channel.

Product, pricing and stock information

There are two ways to get product information from ChannelEngine:

• Via a data feed in XML or CSV - this can be a single, regularly updated feed containing product data (i.e.: details, attributes, and images) and product offers (i.e.: stock and pricing). To get the data feed, go to your custom channel under your development ChannelEngine account and click Product selection. Once you create a product listing, two URLs (one for CSV and one for XML) linking to the data feeds are generated.

• Via the API - All product information can be retrieved via the API /v2/products/data. Every creation, update, and deletion should be acknowledged via an acknowledgement post to the API. This ensures that all updates are reflected on ChannelEngine. Regular stock and price updates can be fetched via /v2/products/offers. This endpoint works in the same way as the product data endpoint, with the main difference that only prices and stock are sent.

Orders

Orders can be created through the API with a POST to /v2/products/orders.

Bear in mind that ChannelEngine does not validate the input, such as phone numbers and addresses. So if you submit the house number under Street name instead of under House number, it causes issues for at least the clients using your channel in the future. To prevent orders from getting 'stuck', make sure to properly validate user input and convert it to the fields expected by ChannelEngine.

Order extra data

You can use the order or order line extra data to submit information specifically for your connection. If you want to include the buyer's username on your platform, for example, for a discount code or for the PayPal transaction ID.

E.g.:

	"ExtraData": { 	"Paypal Transaction Id":"8V793622AB022891Y", 	"Applied Discount":"Summer30%Off"		 } 

Test orders

During development, orders can be updated to a different status on the ChannelEngine web interface. By creating a shipment or cancelation, you can fetch the respective changes via the various endpoints.

Shipments

Shipments can be fetched through /v2/shipments. Each order can have one or more shipments, including track-and-trace information when available. Keep in mind that an order or individual order lines can be split up in multiple shipments. Also, make sure that in most cases you only need to fetch shipments with the status Closed. Shipments with the status Pending do not have complete shipping information yet, so unless you do not use track-and-trace information on your channel, you can ignore these.

Returns

By default, there are two types of returns:

• Returns (merchant) - created by the merchant, when buyers contact the merchant directly. These can be fetched via GET /v2/returns/channel. The easiest solution is to only fetch returns with status Received, but it is possible to fetch other statuses and update accordingly if your channel supports that.
• Returns (channel) - created by the channel, when buyers contact the channel directly. These can be posted via POST /v2/returns/channel. Note that, in this case, you still need to fetch these returns and check if they are marked as Received. Only then the return is complete, and a refund can be processed.

Rate limits

You are limited to a total of 1,000 requests every 15 minutes, shared across all endpoints. The status of the rate-limiting is communicated in the response headers:

• X-Rate-Limit-Limit - the rate limit period. E.g.: 15 minutes.
• X-Rate-Limit-Remaining - the number of requests remaining.
• X-Rate-Limit-Reset - the UTC date and time (in ISO 8601 format) when the limits resets. E.g.: 2021-07-23T015:30:30.

If the limit is reached, you receive an HTTP response status code 429 Too Many Requests.

Make sure to use as few calls as possible, for example by creating and updating products with one call in bulk. Ten calls with 1,000 products each are better than 100 calls with 100 products each. If the limit is still an issue, please contact ChannelEngine's Support team and mention the IP address of the servers you are calling from.

Video: how to find the schema tab

Questions?

If you have questions regarding the API implementation, you can contact your implementation specialist at ChannelEngine or, if they are unavailable, get in touch with the Support team. Make sure to provide them with as much relevant information as possible, so they can help you swiftly and efficiently.