Merchant API: before you start

About this article

This article describes ChannelEngine's Merchant API, as well as the key concepts you need to know before you can start building an integration with it.

Table of contents

Introduction

Get a ChannelEngine account

Key concepts

• Channel
• Ecommerce platform
• Merchant plugin
• Product content
• Product offers
• Orders and order lines
• Shipments
• Cancelations
• Returns and refunds
• Product bundles

Questions

Introduction

To integrate your ecommerce platform with ChannelEngine, you are going to use the Merchant API. This API enables data synchronization between your system and ChannelEngine, reducing the need for manual input.

ChannelEngine’s Merchant API handles the creation of product content and offers, and manages the communication of orders, shipments, cancelations, and returns. This way, your products are purchasable with the right information, price, and stock.

If you use a merchant plugin together with ChannelEngine, the Merchant API also handles the communication between it and the marketplace to ensure that potential buyers are looking at the latest product information.

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

• API reference on OpenAPI/Swagger (select Merchant API in the dropdown menu)
• REST API for merchants
• Merchant API: best practices

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

Get a ChannelEngine account

Before you can start connecting, you need to request an account (known as tenant or environment) for testing purposes. That allows you to authenticate yourself and connect to the Merchant API.

Key concepts

Channel

At ChannelEngine, marketplaces are often referred to as channels. Both terms are used throughout the documentation.

Ecommerce platform

An ecommerce platform is an umbrella term that refers to different types of systems used to manage products, purchases, and user relationships. These include enterprise resource planning (ERP), product information management (PIM), order management systems (OMS), and webshops.

Merchant plugin

A merchant plugin is used to build connections with an ecommerce platform, such as a webshop or management system (e.g.: ERP, OMS, PIM, WMS). This can be a ready-made connection built by ChannelEngine or a custom connection that requires development work to build. ChannelEngine provides a ready-made connection to several ecommerce platforms, such as WooCommerce, Shopify, Adobe Commerce (née Magento), and Katana PIM.

Product content

Product content, or product data, refers to the text, images, and other information used to describe and market products to potential buyers. Although requirements differ per channel, the most common content attributes are the product name, description, highlights, images, and identifier.

You can export product content from your system to ChannelEngine via a direct connection (e.g.: the Merchant API or a product feed) or an indirect connection (e.g.: a third party). You can use the product information required by marketplaces to match the products in your catalog with the products in the channel’s database.

If a product is new to the channel, product content can often be used to ‘create’ the product within it. Note that not every channel supports content creation, that is, the addition of new products to their catalog. Some channels only allow you to match existing product content to your unique product offer.

For more information on required, recommended, and optional content attributes, check out the ChannelEngine: product feeds article.

Product offers

Product offers refer to the price and stock information that you can attach to your products, so they can be purchased by buyers. Although requirements differ per channel, the most common offer attributes are the product’s price, stock, and discount price.

You can export product offers from your system to ChannelEngine via a direct or indirect connection. As mentioned before, channels that do not support content creation can use product offers to match existing products. This approach provides potential buyers with a single source of product content, attached to offers from multiple merchants.

For more information on how to distinguish product content from offers, check out the ChannelEngine: what is the difference between content and offers? article. 

Orders and order lines

Orders are purchase requests made by buyers. They consist of one or more order lines. An order line is the part of an order that contains detailed information about a purchased item. Typically, there is one order line per product in each order. If the quantity of the same product is higher than one in an order, it is grouped in the same order line and the quantity is indicated.

Depending on the marketplace, you can see different tax attributes, such as the VAT, in order overviews. ChannelEngine calculates those taxes automatically. You can see the result by clicking the Show VAT and commission button within the order overview.

For more information on how orders are processed on ChannelEngine, check out the ChannelEngine: orders article.

Shipments

Once an order is processed and ready to be shipped, you need to create a shipment on ChannelEngine. A shipment is the transportation of purchased products to the buyer.

It is important that you provide all the mandatory shipping information. This way, the shipping can be exported back to the channel from which the order came from. Certain channels, such as Zalando and OTTO Market, also require you to provide a return tracking code with the shipping.

For more information on channel-based shipments, check out the following articles:

• External fulfillment: FBA, LVB, FBC, and ZFS
• bol.: verzenden via bol (VVB)
• Amazon: Seller Fulfilled Prime

For more information on how shipments are processed o ChannelEngine, check out the ChannelEngine: shipments article.

Cancelations

Cancelation is the revoking of a placed order. Most channels support cancelations before the order is shipped. After the order has been shipped, buyers cannot cancel them, but they can return the product.

On ChannelEngine, if an order with the status New receives a cancelation request from the marketplace, the order is automatically canceled. This way, ChannelEngine prevents the order from unnecessarily entering the logistic process.

ChannelEngine exports merchant cancelations to the marketplace. Some channels trigger a refund to their customer when receiving a cancelation request from the merchant. But others only accept cancelations when they are handled in their platform directly.

For more information on how cancelations are processed on ChannelEngine, check out the ChannelEngine: cancelations article.

Returns and refunds

A return takes place when a buyer sends a product back to your store or warehouse. A refund involves giving the buyer their money back.

For information on which type of return is supported by each marketplace, check out the ChannelEngine: what channel supports what features? article.

Product bundles

Bundles, or product bundles, are offers that consist of two or more related products. Bundling products is a popular way to generate sales and reduce decision-making pressure.

To sell a bundle on marketplaces, you can manually combine two or more products on ChannelEngine. E.g.: an inkjet printer with additional ink cartridges.

Bundles need their own GTIN, name, and Merchant product number – as they are exported to marketplaces as a different product.

For more information on how product bundles work on ChannelEngine, check out the ChannelEngine: product bundles article.

Questions?

If you have questions regarding the implementation of the Merchant API, you can contact your Integration Coordinator at ChannelEngine or, if they are unavailable, contact the Support team. Make sure to provide as much relevant information as possible, so they can help you swiftly and efficiently.