ChannelEngine: connect 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

Rate limiting

Product, pricing and stock information

Orders

Shipments

Returns

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
• 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).

Rate limiting

To ensure that ChannelEngine can continue serving its customers and partners efficiently and reliably, it is necessary to make use of rate limiting in the Merchant, Channel, and Channel Management APIs. The rate limits defined allow ChannelEngine's customers and partners to perform all calls required to conduct their business in a timely manner.

It is recommended that you make use of dynamic throttling, taking into account the limits and intervals communicated in the response headers.

To request the rate limit for each endpoint you use:

1. Go to ChannelEngine's OpenAPI/Swagger page for your environment. If you do not know its URL, replace the term 'example' in the URL https://example.channelengine.net/api/swagger/index.html with the first part of the URL of your ChannelEngine environment. E.g.: if your ChannelEngine environment is Sustainable Suits, its URL should be https://sustainable-suits.channelengine.net/ and its OpenAPI/Swagger URL should be https://sustainable-suits.channelengine.net/api/swagger/index.html.
2. Click Authorize and, in the Value field, enter your Merchant API key. To find your Merchant API key, log into ChannelEngine and click Settings, Merchant API keys.
3. Click Close and select the endpoint for which you would like to know the limit.
4. Click Try it out. If the endpoint selected requires parameters, make sure to provide them before clicking Execute. Otherwise, click Execute.
5. In the Response headers section, check the values provided by the headers:
   • x-rate-limit-limit - provides you with an interval in minutes.
   • x-rate-limit-remaining - provides you with the number of calls remaining in that interval.

Product, pricing and stock information

There are three 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).

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.

• Mixed

It is also possible to have a mixed approach, with a product feed providing your product information and the API providing stock and price updates.

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.

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.