Merchant API: main resources

About this article

This article describes the most common resources that can be accessed via ChannelEngine's Merchant API.

Table of contents

Introduction

Product content

• Custom attributes (a.k.a. custom fields/product extra data)

Product offers

Orders

Shipments

Returns

Cancelations

Order invoices

Settlements

Introduction

When your ecommerce system communicates with ChannelEngine, it interacts with several resources: product content, product offers, orders, returns, and cancelations. Depending on the type of resource, you may need to call different endpoints and keep in mind certain parameters. This article describes the available endpoints, the suggested methods, and the parameters to be passed in the calls. 

For more information on the Merchant API, refer to one of the following links:

• Merchant API: testing flow
• Merchant API: best practices
• Merchant API data flow: product and offer creation/update

Product content

You can either create content-rich products on ChannelEngine or hook into offers that already exist on the marketplace. In both cases, you need to create a product record with the Merchant product number as a primary key on ChannelEngine.

• Product creation: POST /v2/products

Use this call to create or update existing products.

The provided Merchant product number needs to be unique. If you create a grandparent-parent-child relationship, make sure to first include the grandparent, then the parent, and then the child products. This ensures that the relationship is set up correctly on ChannelEngine.

• Full product update: POST /v2/products

This endpoint is purge and replace, which means that it expects all data – even if you only want to update one attribute. However, you can exclude the stock value by setting the ignoreStock parameter to true.

If you leave out a value from the upsert, it results in the value becoming an empty attribute on ChannelEngine. The value is cleared, and numeric values are changed to zero. This behavior is intended, as otherwise there would be no easy option to clear existing attribute data via the API. This purge-and-replace behavior only applies to ChannelEngine’s default attributes, such as name, description, stock (optionally), price, images, and not to extra data fields (custom fields).

• Partial product update: PATCH /v2/products and PATCH /v2/products/{merchantProductNo}

To update single attributes for multiple products, call PATCH /v2/products. Group all products that need the same attributes updated into one call. For more information on this, check out the article Merchant API: best practices.

Custom attributes (a.k.a. custom fields/product extra data)

Custom attributes are additional data fields that can be exported to a marketplace. These attributes are not predefined by ChannelEngine and typically vary per merchant and marketplace. E.g.: Heel height and Sleeve length. For more information on this, check out the article ChannelEngine: custom attributes.

• Create, update or delete a custom attribute: PATCH /v2/products/extra-dataand PATCH/v2/products/extra-data/bulk

To manage a single custom attribute for a product, use the endpointPATCH /v2/products/extra-data. To manage custom attributes for multiple products, use the bulk endpoint. The format of both endpoints is JSON patch, which allows for partial updates instead of sending the whole JSON document. The supported patch operations are 'add', 'remove', and 'replace'.

Note the Merchant product number of each product must be unique. 

• Retrieve custom attributes: GET /v2/custom-fields

Custom attributes can be added via a product feed, Merchant API, or the ChannelEngine web interface. You can fetch all custom field names, along with information about whether an attribute is public and if it is actively used.

Product offers

• Update stock and/or price: PUT /v2/offer

This endpoint allows you to create and update the stock and price of a single product or multiple products, as it can be used for bulk updates too.

If you make use of ChannelEngine's stock locations feature, make sure to indicate the StockLocationId parameter so ChannelEngine can assign your stock to a specific warehouse.

• Update stock: PUT /v2/offer/stock

To update only the product's stock, use the PUT /v2/offer/stock endpoint. Just like the previous endpoint, you need to include the StockLocationId parameter in the request body.

ChannelEngine can manage stock across multiple stock locations, including stock that is at the marketplace’s warehouse – if supported. To retrieve this information, call GET /v2/stock.

Orders

There are two main reasons why you might need to retrieve orders from ChannelEngine:

1. To fulfill the order, usually retrieved by a WMS, OMS, or ERP.
2. For reporting or accounting purposes. In this case, marketplace-fulfilled orders are also relevant.

• Retrieve merchant-fulfilled orders: GET /v2/orders/new

Merchant-fulfilled orders are orders that must be handled by you. ChannelEngine imports these orders with the status New. You can indicate the stockLocationId parameter to filter orders by the warehouse location.

• Retrieve marketplace-fulfilled orders: GET /v2/orders

Marketplace-fulfilled orders are orders handled by the marketplace. You can retrieve them for administrative and reconciliation purposes. The order is only released by the marketplace once it is shipped, and it is imported into ChannelEngine with the order status Shipped. To apply DateTime filters, use fromCreatedAtDate and toCreatedAtDate as they filter on the date the order is created on ChannelEngine.

This is due to the fact that the order handling time of a marketplace might vary per product, and the channel-fulfilled order might be imported into ChannelEngine only several days after it was created on the marketplace. It is also possible to filter based on the date when the order was updated (i.e.: fromUpdatedAtDate and toUpdatedAtDate), which is useful when retrieving mixed orders.

• Retrieve mixed orders: GET /v2/orders

Mixed orders contain one or more merchant-fulfilled order lines and one or more marketplace-fulfilled order lines. At first, the merchant-fulfilled order lines are imported into ChannelEngine, and an order is created with the status New. These order lines can be handled as regular merchant-fulfilled orders.

Once the marketplace ships the marketplace-fulfilled order lines, these are added to the existing order on ChannelEngine with the order line status Shipped. To retrieve the marketplace-fulfilled order lines of mixed orders, use the DateTime filter fromCreatedAtDate and the filter fulfillmentType = MIXED. This returns mixed orders containing both merchant-fulfilled and marketplace-fulfilled order lines.

Order acknowledgement

Some endpoints require an acknowledgement for the order status 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.

• Acknowledge new orders: POST /v2/orders/acknowledge

After retrieving new merchant-fulfilled orders or order lines, you have to acknowledge them by linking your unique MerchantOrderNo;to the ChannelEngine OrderId of the order.

After an order is acknowledged, its status automatically changes from New to In progress. The next time you call the GET /v2/orders/new endpoint, the already acknowledged orders are not included in the list.

It is also possible to acknowledge marketplace-fulfilled orders. However, in this case, the order status does not change. This is useful to provide you with better filtering options and a clearer overview of orders.

Order troubleshooting 

If you cannot process an order, there are two possible reasons:

• The input is not validated correctly (e.g.: an address field your system can not handle or an SKU that is unknown). In this case, do not acknowledge the order – but correct the input causing the error. In the case of addresses or other buyer information, this can either be done in the ChannelEngine web interface via ChannelEngine's Support. If it is an incorrect SKU (such as an old listing remaining on a marketplace) of a known product, contact ChannelEngine's Support as this can only be corrected in the database.
• The product is not available (e.g.: the SKU sold no longer has any stock, so the order cannot be fulfilled). This depends on your logistical setup and how fast backorders can be delivered. Some ChannelEngine customers auto-cancel orders in this case.

To cancel orders automatically:

1. Acknowledge an order with a unique Merchant order number. This can also be a unique placeholder if the underlying system can only provide IDs for accepted orders.
2. Submit a cancelation for the order via a POST /v2/cancellations call and provide a Merchant order number.

In both scenarios, it is crucial to log your order validation so it is visible to users.

Order details

The parameters that start with Original contain the values in the original currency of the marketplace. The parameters that do not start with Original contain the values converted into the currency selected for the tenant.

E.g.: below is an example of an order created on Amazon Poland. The tenant is configured in euros.

Order lines

It depends on the marketplace if an order can be split into multiple shipments. To find out what support the marketplace provides, call GET /v2/orders or GET /v2/orders/new and check the response parameter ChannelOrderSupport.

All 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/ORDERS) - 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.

One of the most common reasons for errors 4xx is shipments or cancelations with submitted lines that contain an invalid quantity. E.g.:

{"StatusCode":400,"LogId":null,"Success":false,"Message":"Channel requires one shipment line per order line. Incomplete shipment line for order line id 2: expected quantity 3, received 1","ValidationErrors":{}}

To check whether an order or order line can be split, check the ChannelOrderSupport parameter. E.g.:

{ "Content": [ { "Id": 86351, "ChannelName": "bol.com Plaza NL (v3)", "ChannelId": 6, "GlobalChannelName": "bol.com Plaza NL (v3)", "GlobalChannelId": 76, "ChannelOrderSupport": "SPLIT_ORDERS", "ChannelOrderNo": "1107022893"

The example above shows an order from bol.com, which only allows SPLIT_ORDERS. The order can be split into individual order lines, but the order lines themselves can not be split.

Order invoice

Some marketplaces, such as Mirakl-based ones and Amazon, give you the option to choose how you want to handle invoices for orders: get them automatically generated by ChannelEngine or upload them yourself. If you choose to upload invoices yourself, you can do so via the Merchant API.

• Upload invoices for orders: POST /v2/orders/{merchantOrderNo}/invoice

Use this endpoint to upload merchant invoices for orders. Provide a unique Merchant order number for the order and include the invoice in PDF format in the request body. 

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, check out the article How do I create test orders?.

Shipments

The shipment call is a mandatory step to complete the fulfillment of an order. Usually, marketplaces require the following information to accept the shipment:

• Shipping method (i.e.: the name of the carrier fulfilling the order)
• Tracking code

• Mark (part of) an order as shipped: POST /v2/shipments

Use this endpoint to mark an order as shipped on ChannelEngine. Make sure to check the ChannelOrderSupport in the response body when retrieving orders, as not all marketplaces support partial shipments.

With the POST /v2/shipments endpoint, you can either create a complete shipment including tracking information and carrier method, or a draft without tracking information.

Once you have the tracking information, you can update the existing shipment by calling the endpoint PUT /v2/shipments/{merchantShipmentNo}. Note that this update call is purge and replace.

Scenarios

One of the most common questions ChannelEngine receives is: why is my shipment not processed correctly on the marketplace? The main reason for this is that the provided shipment information is missing or incorrect.

If you are implementing an integration with ChannelEngine, take note of the following scenarios and what is valid to submit:

Create a shipment and update tracking information later

1. Create a shipment via POST /v2/shipments. Make sure it contains the Merchant shipment number, the Merchant order number, and at least one order line. Do not include a placeholder method or tracking code, leave them null. If you do submit data in those fields (even if it is a placeholder), the status of the shipment changes to Closed instead of Pending – and ChannelEngine tries to export the shipment to the marketplace. This almost certainly leads to errors at the marketplace, as it considers the tracking information invalid.
2. Once the tracking information becomes available in the seller's system, you can update the shipment via the PUT v2/shipments/{merchantShipmentNo} call. This call must contain the Method (i.e.: the carrier) and the TrackTraceNo. The TrackTraceUrl can be left empty, as most marketplaces generate their own link – which is also why the correct carrier and tracking code are important.
3. It is sometimes necessary to use carrier mapping to select the correct carrier for a marketplace. Bear in mind that your output (i.e.: the Method provided in the shipment), is the input for the carrier mapping. These must match exactly.

Create a shipment and add a tracking code right away

1. Create a shipment via POST /v2/shipments. Make sure it contains the MerchantShipmentNo, the MerchantOrderNo, at least one order line, the Method, and the TrackTraceNo. Also, there must be no empty or null values, and no placeholders.
2. It is sometimes necessary to use carrier mapping to select the correct carrier for a marketplace. Bear in mind that your output (i.e.: the Method provided in the shipment), is the input for the carrier mapping. These must match exactly.

Returns

ChannelEngine’s Merchant API allows you to handle three types of returns:

• Marketplace returns - declared by the marketplace (i.e.: channel). E.g.: the buyer consults the marketplace's customer service or requests the return on the channel's website.
• Merchant returns - declared by you. E.g.: the buyer consults your customer service.
• Marketplace-fulfilled returns - declared and handled by the marketplace, as it is a marketplace-fulfilled order. These are usually retrieved for reporting purposes.

Merchant returns

• Merchant returns: POST /v2/returns/merchant

Use this endpoint to create a return that the buyer handled directly with you. Make sure to provide the quantity of products per order line that you accept as returned. You can also submit the refund amount, inclusive and exclusive of taxes. However, bear in mind that the marketplace normally calculates the refund amount based on the quantity you provided. If the marketplace supports it, parts of an order can be returned and several returns for the same order can be created.

Marketplace returns

• Marketplace returns: GET /v2/returns/merchant, GET /v2/returns with the filter creatorType=ONLY_FROM_CHANNEL, or GET /v2/returns/merchant/new and PUT /v2/returns

Use the GET /v2/returns/merchant, GET /v2/returns with filter creatorType=ONLY_FROM_CHANNEL, or GET /v2/returns/merchant/new endpoints to retrieve returns that were registered at the marketplace. These are returns that a buyer registered with the marketplace but has not sent back to your return address yet.

With GET /v2/returns/merchant/new you can retrieve all unhandled returns. If you prefer to use filters, you can use the GET /v2/returns/merchant, or GET/v2/returns with creatorType=ONLY_FROM_CHANNEL endpoints and filter on the DateTime to implement regular calls to this endpoint.

• Mark a return as received: PUT /v2/returns

Once you receive the return at your warehouse or other return address, mark it as received also on ChannelEngine via the PUT /v2/returns endpoint. In the request body, indicate the quantity you accept (i.e.: AcceptedQuantity) and the quantity you reject (RejectedQuantity). Note that the AcceptedQuantity plus the RejectedQuantity must be equal to the full quantity of the announced return. The buyer is refunded based on the accepted quantity. Note that you cannot update a channel return more than once.

Marketplace-fulfilled returns

• Marketplace-fulfilled returns: GET /v2/returns/merchant or GET /v2/returns with the filter creatorType=ONLY_FROM_CHANNEL

You can retrieve the returns of channel-fulfilled orders for reconciliation purposes by calling the endpoint GET /v2/returns/merchant or GET/v2/returns with creatorType=ONLY_FROM_CHANNEL and using the DateTime filter fromDate and the fulfillmentType filter set to ONLY_CHANNEL for channel-fulfilled orders – or MIXED for mixed orders.

Acknowledge returns

Returns can be created, fetched, marked as received, and acknowledged via the API. To retrieve only the latest returns from the marketplaces, 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.

To acknowledge returns if you just started working with ChannelEngine:

1. Call the GET /v2/returns/merchant endpoint.
2. Use the following parameters:
   • statuses - in_progress
   • isAcknowledged - false
3. Call the POST /v2/returns/merchant/acknowledge endpoint to acknowledge new returns.

To acknowledge returns if you have been working with ChannelEngine for some time:

1. Call the GET /v2/returns/merchant endpoint.
2. Use the following parameters:
   • statuses - in_progress
   • isAcknowledged - false
   • fromDate - enter the date from which you want to start acknowledging returns.
3. Call the POST /v2/returns/merchant/acknowledge endpoint to acknowledge new returns.

To retrieve and acknowledge marketplace-fulfilled returns:

1. Call the GET /v2/returns/merchant endpoint.
2. Use the following parameters:
   • fulfillmentType- ONLY_CHANNEL
   • isAcknowledged - false
3. Call the POST /v2/returns/merchant/acknowledge endpoint to acknowledge new returns.

Cancelations

Orders can be canceled via ChannelEngine’s Merchant API when:

• You are unable to fulfill the order. E.g.: the remaining stock got destroyed or lost.
• The cancelation request came from the marketplace. On some marketplaces, the buyer can cancel their order within a specific timeframe. If the order is retrieved by ChannelEngine, but not yet by you, ChannelEngine automatically cancels the order. However, if the order has already been retrieved by you, ChannelEngine flags it as ‘cancelation requested’. In this case, it is up to you to either accept or reject the order.

• Mark (part of) an order as canceled: POST /v2/cancellations

Use this endpoint to create a cancelation. Indicate the quantity of products you want to cancel and include the reason for the cancelation (e.g.: not in stock). The reason can be used later for statistical purposes.

• Retrieve a cancelation request from the marketplace: GET /v2/orders with the filter onlyWithCancellationRequests

After you retrieve an order with a request for cancelation, you can create a cancelation of that order using the previously mentioned POST /v2/cancellations endpoint.

Order invoices

Some marketplaces allow you to upload invoices for your orders. You can submit order invoices via the Merchant API.

• Upload invoices for orders: POST /v2/orders/{merchantOrderNo}/invoice

Use this endpoint to upload merchant invoices for orders. Provide a unique Merchant order number for the order and include the invoice in PDF format in the request body.

If your system does not support PDF invoices and can only process text, you can use Base64 encoding for your order invoices. To provide the invoice in the Base64 format to ChannelEngine, send a request to the POST /v2/orders/{merchantOrderNo}/invoice-base64 endpoint – including the invoice content and invoice number in the body of the request.

Settlements

Every payment a marketplace performs toward a merchant is included in a settlement report. This report contains information on transactions and other financial activity, which can help you reconcile the totals you see on ChannelEngine or your merchant system and the amount received from the marketplace.

Retrieve settlements

To retrieve a settlement report in CSV format via the Merchant API, do the following: 

1. Reach out to your customer success manager on ChannelEngine or contact ChannelEngine's Support to enable the Settlement report feature. Once the Settlement report feature is active, ChannelEngine initiates the import of settlement files issued 14 days ago and up until the present time.
2. Retrieve the IDs of available settlements via the GET /v2/settlements endpoint. Filter by the Channel ID parameter and by date, from a specific date to another specific date. Once you get the Settlement ID, you can use it to retrieve reports.
3. Request a settlement report via the POST /v2/reports/settlements endpoint. Indicate the Settlement ID and the type of report (i.e.: CUSTOM_JSON or DETAILED). This returns a Report ID formatted as a GUID (i.e.: globally unique identifier). E.g.: 3fa85f64-5717-4562-b3fc-2c963f66afa6.
   • Custom JSON - a custom report containing your selected transactions. To configure a custom report, define a JSON file in the settlement export plugin. To learn more, check out the article ChannelEngine: custom settlement reports.
   • Detailed - a detailed report containing all transactions. It includes the currency, transaction type, order date, VAT, and net/gross amount.
   NB: depending on the number of transactions within the settlement, it can take a few minutes for the report to be generated.
4. Check the status of the report creation progress via the GET /v2/reports/{reportId}/status endpoint. Indicate the Report ID in the call. This returns the status of a report. If the status is Done, the response contains a URL with a download path.
5. Retrieve the report via the GET /v2/reports/{reportId} endpoint. Indicate the Report ID in the call. If the report is available, you can download it as a CSV file with a semicolon (;) as a delimiter.

Upload settlements

For marketplaces that do not provide settlement reports to ChannelEngine via the API, such as Zalando and ManoMano, you can manually upload the settlements to ChannelEngine.

To upload the settlement, use the POST /v2/settlements/upload endpoint. Indicate the Channel ID parameter in the call and attach the file in the request body of the call.