ChannelEngine: connecting to the Merchant API

About this article

This article describes the Merchant 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 your enterprise resource planning (ERP) or ecommerce platform to ChannelEngine, you can either use ChannelEngine's Merchant API or a combination of the Merchant API and data feeds (be them XML- or CSV-based).

For more information on the Merchant API, check the links below:

• API reference (OpenAPI/Swagger) - select the Merchant API
• REST API for merchants
• REST API for channels
• Merchant API: best practices

Before using ChannelEngine's Merchant API, check out ChannelEngine's extensions for ecommerce platforms.

Using the API

When operating the Merchant API, make sure to use your personal subdomain .channelengine.net (e.g.: myshop-nl.channelengine.net).

Product, pricing and stock information

There are two ways to update product information on 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).

OR

If you have a vast 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 (e.g.: every 15 minutes, depending on the sales volume and stock levels).

To add a data feed, go to Products > Product feeds on ChannelEngine.

• Via the API

All product information can be inserted and updated via the API as well. It makes sense to add new products once, and update product information when these products are updated. You can call ChannelEngine's API to acknowledge these updates for every stock or price change.

Orders

Orders can be fetched, acknowledged, or canceled via the API. The recommended endpoint to fetch orders is /v2/orders/new. However, you can also use the /v2/orders endpoint, which allows for filtering on statuses and attributes (e.g.: is the order fulfilled by the merchant or by the channel?).

Test orders

During development, it can be useful to have test orders on ChannelEngine. You can create multiple test orders under Settings > Support in your ChannelEngine account. For more information on how to create test orders, check out How do I create test orders?.

Shipments

Each order can have one or more shipments, including track-and-trace information when available. Track-and-trace data is a requirement for most channels to track shipment performance. The availability of an option to split orders or individual order lines in multiple shipments varies per channel. This information can be found by checking the ChannelOrderSupport on an order or the What channel supports what features? article. The possible options are listed below:

• 0 (NONE) - the channel does not support any orders or order follow-up actions. E.g.: Beslist does not support automated shipments or returns, therefore it is not possible to perform any partial order actions.
• 1 (NO_SPLIT) - the channel supports orders and follow-up actions, but these cannot be split. If an order has two order lines, both must be included in a single shipment.
• 2 (SPLIT_ORDERS) - the channel supports orders and follow-up actions, but they can only be split into individual order lines. An order containing two separate products can be shipped in two shipments, with each shipment containing one product. However, an order line cannot be split. If there is a quantity of three for an ordered product, only the total number of three items can be either shipped or canceled, for instance.
• 3 (SPLIT_ORDER_LINES) - the channel supports orders and follow-up actions, and can be split per each individual product. If there is a quantity of three ordered for a product, it is possible to ship two items and cancel one item, for instance.

NB: shipments are not exported to channels without a carrier method and track-and-trace information. Make sure to provide this in your shipment calls, either right away or later via a PUT /v2/shipments/{merchantShipmentNo}, containing the Method and TrackTraceNo. The TrackTraceUrl is optional, most channels ignore it and create their own – but if you have the data do include it.

Returns

You can retrieve all returns created by a channel via the API, or create a new return if the channel supports it. To see what kind of return options are available (i.e.: channel returns, merchant returns, both, or none), consult the related channel guide.

You can mark an order or part of it as returned by the customer when you receive it in your warehouse.

Rate limits

You are limited to 10,000 requests every 15 minutes. 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 a 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 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 Integration Coordinator at ChannelEngine or, if they are unavailable, email the Support team. Please provide them with as much relevant information as possible, so they can help you swiftly and efficiently.