Connecting to the Merchant API

// Contents

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

// Introduction

In order to connect your ERP or e-commerce platform to ChannelEngine, you can use the Merchant 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:

Before you start using our API you might want to check our range of extensions for common e-commerce platforms.

// 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 updated to ChannelEngine:

  1. Via a data feed in XML or CSV. (Reference found here)
    This can be a single regularly updated feed containing both product details, attributes, and images as well as stock and pricing.

    or

    When you have a large product catalog, it makes sense to provide a separate data feed on a daily basis while generating a separate offer feed, containing only stock and pricing, which is updated on a regular basis (eg. every 15 min, depending on the sales volume and stock levels). 
  2. Adding a data feed can be done by going to your ChannelEngine account and go to Products > Product feeds.
  3. Via the API (Reference found here)
    All product information can be inserted and updated via the API as well. Usually, it makes sense to add new products once and update product information when these products update. For every stock or price change, you can call our API to reflect these updates when they happen.

// Orders

Orders can best be fetched, acknowledged, or canceled via the API. We strongly advise using the /v2/orders/new endpoint for getting orders, but you are free to use the /v2/orders endpoint which allows filtering on status and attributes (like is the order merchant or channel fulfilled?). 

/ Test orders

During development, it can be useful to have test orders in ChannelEngine. You can create multiple test orders mimicking a live situation by going to Settings > Support in the ChannelEngine account. You can find more information on how to create these test orders here: https://help.channelengine.com/article/67-how-do-i-create-test-orders.

// Shipments

Each order can have one or more shipments that need to be sent to ChannelEngine including track & trace reference where available. This track & trace reference is a requirement for most marketplaces in order to track shipment performance. If an order or individual order lines can be split up in multiple shipments, is depending on the support the channel has for this. This information can be found by checking the ChannelOrderSupport on an order. Possible options:

  • 0 (NONE) - this means the channel does not support any orders or order follow-up actions. For example: Beslist does not support automated shipments or returns, so therefore it's not possible to perform any (partial) order actions.
  • 1 (NO_SPLIT) - this means the channel supports orders and follow-up actions, but these can not be split. If an order has 2 order lines, this means both will have to be included in 1 shipment.
  • 2 (SPLIT_ORDERS) - this means the channel supports orders and follow-up actions, but they can only be split into the individual orderlines. This means that an order containing 2 separate products can be shipped in 2 shipments (each shipment containing one product). However, an order line in itself can not be split. So if there is a quantity of 3 for one product is ordered, only the total number of 3 items can be shipped or canceled. 
  • 3 (SPLIT_ORDER_LINES) - this means the channel supports orders and follow-up actions and can be split per each individual product. If there is a quantity of 3 ordered for one product, you can ship 2 items and cancel 1 item for example.

Please note that for marketplaces, shipments will not be exported without a carrier method and track&trace number. Be sure to supply this in your shipment calls, either right away or by doing a  PUT /v2/shipments/{merchantShipmentNo} later containing the Method and TrackTraceNo. The TrackTraceUrl is optional (most marketplaces will ignore it and create their own), but if you have the data please include it.

// Returns

Get all returns created by the channel via the API or create a new return if the channel supports it. To see what kind of return options are available (channel returns, merchant returns, both or none), please consult the individual marketplace guide to see what's supported.

You can separately mark (part of) an order as returned by the customer when received in your warehouse.

// Rate limits

You are limited to 1.000 requests in 15 minutes. 

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.