Connecting to the Channel API

// Contents

Introduction
Using the API
Product-, pricing- and stock information
Orders
Shipments
Returns
Rate limits
Questions

// Introduction

In order to connect a new marketplace or e-commerce platform as a sales or data channel to ChannelEngine, you can use the Channel REST API. Or a combination of the API and data feeds (XML or CSV).

The most up-to-date information can be found through the links below:

// Using the API

When using the API, make sure to use your personal subdomain  <shopname>.channelengine.net (e.g. myshop-nl.channelengine.net).

// Product-, pricing- and stock information

There are two ways to get product information from ChannelEngine:

  1. Via a data feed in XML or CSV. 
    This can be a single regularly updated feed containing both product details, attributes, and images as well as stock and pricing. Getting the data feed can be done by going to your custom channel in your development ChannelEngine account where you can go to Product selection. Create a product listing and you will find 2 URLs (CSV and XML) that link to the data feeds that are generated
  2. Via the API (Reference found here)
    All product information can be retrieved via the API /v2/products/data. Every creation, update or delete should be acknowledged by doing an Acknowledgement post to the API. This will make sure that all updates are reflected in the ChannelEngine dashboard and processes as well. Regular stock and price updates can be fetched through /v2/products/offers. This endpoint works the same as the product data endpoint with the main difference that only prices and stock will be sent. 

// Orders

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

Please be aware that in case of our API, we can not do any validation on the input (for example for addresses). So if you submit the house number in the street name field and leave it from the house number field, this will cause issues for at least of the clients wanting to use your channel in the future. Therefore make sure you properly validate user input and convert it to the fields ChannelEngine expects to prevent orders getting 'stuck'.

/ 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.

Example:

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

During development, orders can be updated to a different status in the ChannelEngine web interface. By creating a shipment or cancellation, you should be able to 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 & trace reference where available. Please 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 will only need to fetch shipments with the status CLOSED. Shipments with the status PENDING are shipments that do not yet have complete shipping information, so unless you do nothing with Track&Trace information on your channel, please ignore these.

// Returns

Please be aware that by default there are 2 types of returns:

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

// Rate limits

You are limited to a total of 1.000 requests in 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. 15m) X-Rate-Limit-Remaining: number of requests remaining X-Rate-Limit-Reset: UTC date time (in ISO 8601 format) when the limits resets

If the limit is reached, you will receive a response with HTTP status 429 (Too many requests).

Make sure you are using as few calls as possible, for example by creating/updating products with one call in bulk. 10 calls each containing 1000 products is better than 100 calls containing 100 products. If the limit is still an issue, contact support and mention the IP address of the server(s) you're calling from.

// Questions?

When you have any questions regarding the API implementation you can either contact your ChannelEngine integration coordinator or if unavailable, email our support team via support@channelengine.com. Please provide as much relevant information as possible so our team can help you in the most efficient way.