Merchant API: best practices
About this article
This article contains guidelines to improve the quality and resiliency of implementations of ChannelEngine's Merchant API.
Table of contents
When you build an integration with the ChannelEngine Merchant API, it is crucial to implement all calls properly – and include fallbacks to handle incorrect calls or unavailable services.
Following the guidelines in this article – as well as going through the testing flow and the data flow – increases the chance of a successful implementation.
For more information on the Merchant API, refer to one of the following links:
- Merchant API: conventions
- Merchant API data flow: orders, shipments, and cancelations
- Merchant API data flow: channel and merchant returns
ChannelEngine's teams have seen many integrations that were not fully tested – and issues came to light when the integration was already in production. Therefore, it is crucial to check your testing flow and compare it with ChannelEngine's standard test flow to see if you missed any specific parts of the integration.
For more information on the testing flow, check out the article Merchant API: testing flow.
If you perform a valid API call with valid content and ChannelEngine's services are fully online, you receive a
2xx status code. This means the data submitted was processed correctly. This is the case for 99.9% of the calls handled by ChannelEngine's Merchant API.
Nevertheless, it is critical to build checks and retries in case of a
5xx status code. Make sure to also check the validation message on statuses
200, when using the product and offer endpoints, to see if you submitted items in bulk (which you should) – and if there were validation errors on some of these items.
For more information, check out the article Merchant API: errors and response codes.
It is highly recommended to submit incremental updates of product or offer data to ChannelEngine. However, make sure to include an option on your end to trigger an export of all data.
A good setup exports all incremental changes since the last export every five, ten, or 15 minutes.
Bear in mind that the offer endpoint can only be used for updating price and stock. Some integrations depend on the purchase price or other (custom) price attribute to determine sales prices, in which case you need to use the
/v2/products endpoint to update that information.
A good setup exports all incremental changes since the last export every 30 or 60 minutes. If you have few product data changes during the day, you can also limit this to once or twice a day.
This endpoint is used to update fields on a single product. Using this endpoint you only have to provide the value for the field you wish to update or clear. This endpoint uses a JSON Patch document format. More information on this can be found on What is JSON Patch?. Using the operation 'replace', a value can be updated. Using the operation 'remove', a value can be cleared. One of the advantages of the PATCH endpoint over the POST endpoint is that there is no need to provide all product information, just the field that has to be updated.
Bear in mind that this endpoint is purge and replace, so even incremental updates must contain all product data for the product you want to update.
Regardless of the type of update, make sure to build in a manual option to export everything or at least the stock. Combined with building retries based on error codes, this prevents data from not being synchronized for whatever reason (e.g.: disruptions, failed API calls, invalid data, etc.) – resulting in lost data, and no possibility to update again. When connecting to marketplaces or merchant integrations, ChannelEngine uses a similar method to ensure that incremental updates are exported and retried in case of failure, but with an option on its end to re-export all data if needed.
Some endpoints require an acknowledgement for the status of the order to be changed and to make follow-up actions possible. The most important endpoint is
GET /v2/orders/new. If an order is not acknowledged, it remains on status New and is returned indefinitely as a new order.
Make sure that after you fetch new orders you acknowledge them via
For more information, check out the article Merchant API: main resources.
You can create, fetch, and acknowledge returns via the API. To retrieve only the latest returns from the marketplaces you can use the
POST /v2/returns/merchant/acknowledge endpoints. With the
isAcknowledged parameter, you can identify the returns that are already registered to fetch only unknown returns.
For more information, check out the article Merchant API: main resources.
One of the most common questions ChannelEngine receives is: Why is my order not fetched or stuck as New? This is, unfortunately, a question that ChannelEngine is unable to answer precisely.
With the exception of the API not being available and/or the state of the order changed to something else, the API returns all available information on orders. If your system/integration cannot process the order for whatever reason (e.g.: invalid address, out of stock, unknown product, etc.), it is highly recommended to make this visible to those using your system. As ChannelEngine has no insight into the reason why an order is not accepted or acknowledged, it has to refer users back to someone who does have technical insight into the integration for further investigation.
By adding logging visible to users during the development, orders that remain open for a long period and complex investigations can be avoided.
To use pagination, you must include the
page parameter in your call. In the example below, all orders with the status
fromDate equal to
2021-01-01 are retrieved, as long as they belong to page 2 on the list:
GET "https://demo.channelengine.net/api/v2/orders?statuses=SHIPPED&fromDate=2021-01-01&page=2&apikey=*******" -H "accept: application/json"
Several endpoints can return a paginated response. These endpoints include:
If there are more than 100 results for any of those endpoints, there are multiple pages returned. Therefore, it is recommended that you build support for fetching additional pages. You can use the following attributes on responses to check the number of results and available pages:
ItemsPerPage– indicates the number of results per page. The maximum number of results per page is 100.
TotalCount– indicates the total number of results available. If you divide it by the
ItemsPerPage, you get the total number of pages to be fetched.
Count– indicates the number of results on the last page.
"Count": 100, "TotalCount": 18920, "ItemsPerPage": 100,
In the example above, the total number of response items is 18,920. Divided by the maximum number of items per page (i.e.: 100), it results in 190 pages to be fetched.
For more information on pagination in ChannelEngine's APIs, check out ChannelEngine's OpenAPI documentation.
Many endpoints of the ChannelEngine Merchant API are bulk endpoints, and are meant as such. The two most important endpoints are:
While it is not a problem to include only one product in an incremental
/v2/products call if, for that period, this is the only update, it is a problem if you want to update 10,000 products and do so in 10,000 separate calls at the same time.
When developing a connection with the Merchant API, use the following guidelines:
Make calls in batches
If you want to update 500 products, do one call with 500 products in it. To upsert or delete 100,000 products, split this up into ten batches of 10,000 products.
Do not send multiple batches simultaneously, especially if there is overlapping content
Scenario A - if you submit several separate shipments for one order with multiple order lines simultaneously, the order status does not change to Shipped – it remains on In progress. This is due to the fact that the shipments are processed at the same time, and during processing, the various threads are not aware of the results of the others.
When processing one shipment and checking the remaining open order lines, all other order lines, are considered open – so the status of the order does not have to be updated yet. You can prevent this by submitting the shipments with an interval of 2-3 seconds.
Scenario B - if you submit an offer update containing 50,000 products (be it batched or not) and submit another offer update 30 seconds later containing several of the same products from the first update, you are likely to get errors from the API. The database is still 'locked' while processing the updates from the first 50,000 products.
Although it is possible to send frequent offer updates (e.g.: every 5-10 minutes), bear in mind that, based on the total number of updates, there are limits on how often certain data can be updated.
If you receive
error 429, you have made too many requests
You are limited to a set number of requests per endpoint. The status of the rate limiting is communicated in the response headers. If you batch and schedule your bulk calls, this limit should never be reached. For the sake of comparison, Amazon has a limit of 30 calls per hour, shared across all EU countries, on their Feeds API.
For more information on the use of rate limiting in ChannelEngine's Merchant API, check out the article Merchant API: rate limiting.
Prevent superfluous API calls
|Use case||Fetch all returns from the past three months, keeping them up-to-date every ten minutes.|
|First API call:
Then loop over the pages using the following:
and so on.
If the newest return in this list has the property
Plan your API calls based on the rate limit response headers received
|Use case||Fetch all shipments to cross-check if everything has been created correctly.|
|Best practices||Use the
Fetch new order information efficiently
|Use case||Fetch new orders.|
|Best practices||Use the API endpoint on a fixed timeframe (e.g.: every ten minutes to fetch all the new orders) by calling the endpoint, importing the orders, and then acknowledging each one. If the