Merchant API: main resources

About this article

This article describes the most commonly used endpoints in the Merchant API.

Table of contents

Introduction

Product content

Product offers

Orders

Order documents

Shipments

Returns

Cancelations

Settlements

Revenue targets

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 fields

Custom fields 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 fields.

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

To manage a single custom field for a product, use the endpointPATCH /v2/products/extra-data. To manage custom fields 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 fields: GET /v2/custom-fields

Custom fields 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 a custom field is public and if it is actively used.

• Delete multiple custom fields: DELETE /v2/custom-fields

Use this endpoint to delete multiple custom fields based on their IDs. Indicate the IDs of the custom fields for deletion. Note that you cannot delete custom fields that are assigned to a certain product or are actively used on ChannelEngine, such as in mappings.

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, 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

Retrieve both merchant-fulfilled and marketplace-fulfilled orders via the Merchant API. Merchant-fulfilled orders are orders that are handled by you. Marketplace-fulfilled orders are orders handled by the marketplace. 

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

When you are prepared to process a merchant-fulfilled order, acknowledge the order with the following endpoint: 

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

For more details on how to manage orders via the Merchant API, check out Merchant API: orders.

Order documents

You can import a list of order documents from ChannelEngine to your merchant system and download the documents, including shipping and return labels, if they are offered by your channels.

• Retrieve the list of order documents: GET /v2/orders/documents with filters

Use this endpoint to retrieve a paginated list of order documents. You can filter by specific orders using the ChannelOrderNo or MerchantOrderNo identifiers. 

You can also indicate a date range or filter by a document type. To only retrieve documents that have not been acknowledged by your system yet, use the onlyUnacknowledgedByMerchant filter.

The response includes the metadata for each document matching the filter criteria.

• Retrieve an order document file: GET /v2/orders/documents/file

Use this endpoint to download a specific order document. You must specify the DocumentID, which you can retrieve from the GET /v2/orders/documents endpoint. The response contains a file in PDF or XML format.

• Acknowledge order documents: POST /v2/orders/documents/acknowledge

After downloading an order document, use this endpoint to confirm its receipt in your system. Include the DocumentId in the request body. Once acknowledged, the document's IsMerchantAcknowledged value is set to true. Note that only documents imported by ChannelEngine can be acknowledged.

Refer to the respective channel guide to find out which endpoint to use to retrieve and download your shipping labels, as the endpoint used for downloading shipping labels can vary from channel to channel. 

For more guidance on managing order documents on ChannelEngine, check out Order documents.

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 and mark an order as shipped:

• 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 either create a finalized shipment, including tracking information and carrier method, or a draft, without tracking information. To find out if the channel accepts partial shipments, check the ChannelOrderSupport field in the response body when you retrieve the order via API, as not all channels support partial shipments.

For more guidance on creating your shipments via the Merchant API, check out the article Merchant API: shipments.

Returns

• Create a merchant return: POST /v2/returns/merchant

Use this endpoint to create a return that the buyer handled directly with you. 

• Retrieve marketplace returns: GET /v2/returns/merchant

Use this endpoint to retrieve returns that the buyer handled directly with the marketplace. Then, acknowledge the marketplace return.  

• Acknowledge a return: POST /v2/returns/merchant/acknowledge

Mark the items as received at your warehouse to further process the buyer's refund. The buyer is typically refunded based on the accepted quantity. 

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

For more guidance on using the v2 endpoints to manage returns, check out Merchant API: returns.

For details on using the v2.1 endpoints to manage returns and refunds, check out Merchant API: returns and refunds v2.1 [beta].

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.

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.

Revenue targets

You can set monthly revenue targets and track your financial progress by comparing the actual gross merchandise value (GMV) to your targets.

You can capture the following targets per month:

• Including VAT
• Excluding VAT

In addition, you can set targets for a specific marketplace or globally, at the tenant level.

To learn more about setting up targets via the web interface, check out the article ChannelEngine: revenue targets.

• Create revenue targets: POST /v2/targets

Use this endpoint to set one or more revenue targets. Indicate the target amount (either including or excluding VAT), ID of the channel, month, and year, just as you would in the web interface. The month must be a numeric value, e.g.: 1 for January, 2 for February, and so on. If you do not indicate a specific month, the same target applies to all months within that year.

• Update revenue targets: PUT /v2/targets

Use this endpoint to update one or more revenue targets. Indicate the target amount (either including or excluding VAT), ID of the channel, month, and year your target is for. The month must be a numeric value, e.g.: 1 for January, 2 for February, and so on. If you exclude the channel ID, the target applies globally – across all connected marketplaces.

• Delete revenue targets: DELETE /v2/targets

Use this endpoint to delete one or more revenue targets. Indicate the ID of the channel, month, and year your target was meant for. Providing only the year is not sufficient to delete a target, make sure you indicate the month(s).