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

Introduction

Test your integration

Check and log the response code

Use incremental updates, but add an option to (re-)export all

Acknowledge orders

Acknowledge returns

Log your order validation for users (show why an order is not acknowledged)

Build support for paginated responses

Do bulk calls

Scenarios

Introduction

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.

Test your integration

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.

Check and log the response code

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 4xx or 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.

Use incremental updates, but add an option to (re-)export all

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.

Offers

PUT /v2/offer

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.

Data

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.

PATCH /v2/products

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

POST /v2/products

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.

Acknowledge orders

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 POST /v2/orders/acknowledge.

For more information, check out the article Merchant API: main resources.

Acknowledge returns

You can create, fetch, and acknowledge returns via the API. To retrieve only the latest returns from the marketplaces you can use the GET v2/returns/merchant/ and 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.

Log your order validation for users (i.e.: show why an order is not acknowledged)

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.

Build support for paginated responses

To use pagination, you must include the page parameter in your call. In the example below, all orders with the status Shipped and fromDate equal to 2021-01-01 are retrieved, as long as they belong to page 2 on the list:

curl -X
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:

• GET /v2/notifications
• GET /v2/orders
• GET /v2/returns/merchant
• GET /v2/products

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.

Do bulk calls

Many endpoints of the ChannelEngine Merchant API are bulk endpoints, and are meant as such. The two most important endpoints are:

• PUT /v2/offer
• POST /v2/products

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 100,0000 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 an 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.

Scenarios

Prevent superfluous API calls

Use case	Fetch all returns from the past three months, keeping them up-to-date every ten minutes.
Endpoint	GET /v2/returns/merchant
Best practices	Use the fromDate parameter to filter on the creation date. In the first run, set the fromDate to three months in the past. Check whether all data is imported. On the next import run, ten minutes later, use the createdAt date of the newest imported return – with a tolerance of one hour to make sure you do not miss anything – as the new fromDate for the API call, instead of again fetching all the returns of the last three months.
	First API call: https://YourTenant.channelengine.net/api/v2/returns/merchant?fromDate=2022-09-01 00:00:00.000&page=1
	Then loop over the pages using the following: https://[your-tenant].channelengine.net/api/v2/returns/merchant?fromDate=2022-09-01 00:00:00.000&page=2 https://[your-tenant].channelengine.net/api/v2/returns/merchant?fromDate=2022-09-01 00:00:00.000&page=3 and so on.
	If the newest return in this list has the property createdAt: "2022-09-15T09:45:10.692Z", for instance, use the following request in the next call to fetch returns: https://[your-tenant].channelengine.net/api/v2/returns/merchant?fromDate=2022-09-15 08:45:10.692&page=1

 

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.
Endpoint	GET /v2/shipments/merchant
Best practices	Use the fromCreateDate parameter to specify a start date for your report and iterate through the pages of shipments by increasing the Page parameter on every call. Make sure to check the X-rate-limit-remaining header parameter on every call, so you are aware of the remaining number of API calls available. Once this limit is one, stop making calls after your next call and wait until the limit is restored.

 

Fetch new order information efficiently  

Use case	Fetch new orders.
Endpoint	GET /v2/orders/new
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 TotalCount in the response is higher than the Count, fetch the next page and import and acknowledge every order.