Merchant API: settlements

About this article

This article explains how to retrieve, upload, and manage settlement reports via the ChannelEngine Merchant API, including the multi-step report generation workflow and the upload endpoint for marketplaces that do not provide settlements via API.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

Retrieve settlement IDs

• Endpoint: retrieve settlements

Generate a settlement report

• Endpoint: request a settlement report
• Endpoint: check report status
• Endpoint: download the report

Upload settlement files

• Endpoint: upload a settlement file

Common issues

Next steps

Introduction

Every payment a marketplace performs toward a merchant is included in a settlement report. Settlement reports contain a breakdown of all financial transactions in a given period, including order proceeds, buyer refunds, and fees deducted by the marketplace. Use them to reconcile the totals you see on ChannelEngine or in your merchant system with the amount actually received from the marketplace.

ChannelEngine automatically retrieves settlement reports from connected marketplaces that provide them via API, including Amazon, bol, eBay, Mirakl-based marketplaces, and Walmart, among others. For marketplaces that do not provide settlements via API, such as Zalando and ManoMano, you can upload the report files manually using the POST /v2/settlements/upload endpoint.

This article covers the Merchant API endpoints for retrieving settlement IDs, generating downloadable reports, and uploading settlement files for marketplaces that require manual imports.

Overview

Refer to the flowchart below to visualize how settlement data flows between the marketplace, ChannelEngine, and your merchant system.

Requirements

Before using the settlements endpoints, ensure you have the following:

• A valid Merchant API key. Generate one in your ChannelEngine account at Settings, Merchant API keys. For more information, check out the article Merchant API: getting started.
• Your tenant's base API URL in the format https://<your-subdomain>.channelengine.net/api.
• The Channel ID of the marketplace you want to retrieve or upload settlements for. You can find this in the channel settings on ChannelEngine.
• To export settlement reports in a custom format, ensure the Settlement export plugin is added to your tenant. For more information, check out the article ChannelEngine: settlement export and customization.
• Verify that the given marketplace allows managing settlement reports via API. For detailed guidance, check out the Supported marketplaces section of ChannelEngine: settlement reports.

Available API endpoints

The following endpoints cover all settlement-related operations in the Merchant API.

• Retrieve settlements: GET /v2/settlements
  Retrieve a list of available settlements and their IDs. Filter by Channel ID and date range to narrow results. The Settlement ID returned by this endpoint is required for subsequent report generation calls.
• Request a settlement report: POST /v2/reports/settlements
  Trigger the generation of a settlement report for a given Settlement ID. Returns a Report ID that you use to check generation status and download the finished report.
• Check report status: GET /v2/reports/{reportId}/status
  Poll this endpoint to check whether a report has finished generating. When the status is Done, the response contains a download URL.
• Download a report: GET /v2/reports/{reportId}
  Download the generated settlement report as a CSV file. Reports are available for 90 days from generation.
• Upload a settlement file: POST /v2/settlements/upload
  Upload a settlement file for a marketplace that does not provide settlement data via API. Attach the file in the request body and indicate the Channel ID.

Retrieve settlement IDs

ChannelEngine automatically imports settlement files from connected marketplaces. By default, it initiates the import of settlement files issued within the past 14 days. To retrieve a list of available settlements and their IDs, call GET /v2/settlements.

Endpoint: retrieve settlements

• Method and path: GET /v2/settlements

Use the following query parameters to filter the results:

The response returns a list of settlement records. Each record includes:

• Id - the Settlement ID. Use this value in the POST /v2/reports/settlements call.
• ChannelReference - the unique reference assigned to the settlement by the marketplace. This matches the payout item in your bank statement.
• Status - either New or Acknowledged. Acknowledged settlements have already been exported to your system.
• PaymentAmount - the total payment amount for the settlement, as provided by the marketplace.
• StartDate / EndDate - the start and end of the settlement period.
• CreatedAt - the date and time when ChannelEngine saved the settlement to its database.

Generate a settlement report

Generating a settlement report is a three-step asynchronous process: request the report, poll for completion, then download the file.

Endpoint: request a settlement report

• Method and path: POST /v2/reports/settlements

Include the following parameters in the request body:

The reportType values are:

• DETAILED - a detailed report containing all transactions. It includes the currency, transaction type, order ID, VAT, and net/gross amount.
• DETAILED_EXTENDED - a report that contains all the fields as the Detailed option does, with the addition of the following fields per row: ChannelId, GlobalChannelId, ChannelName, StartDate, EndDate, CurrentReserveAmount, PreviousReserveAmount, ReserveMutationAmount, PaymentAmount.
• CUSTOM_JSON - a custom settlement report. You specify which data to include in the report. To define the JSON file of the custom report, check out ChannelEngine: settlement export and customization.

A successful response returns a Report ID formatted as a GUID. E.g.:

3fa85f64-5717-4562-b3fc-2c963f66afa6

Use this Report ID in the next two steps.

Endpoint: check report status

• Method and path: GET /v2/reports/{reportId}/status

Replace {reportId} with the GUID returned by POST /v2/reports/settlements. Poll this endpoint at a reasonable interval until the status changes to Done.

When the status is Done, the response body contains a download URL for the report file.

Endpoint: download the report

• Method and path: GET /v2/reports/{reportId}

Replace {reportId} with the GUID from the earlier POST call. If the report is available, the response is a CSV file using a semicolon (;) as a delimiter.

Upload settlement files

Some marketplaces do not provide settlement data to ChannelEngine via API. For these marketplaces, including Zalando, ManoMano, and BestSecret, you can upload settlement files directly to ChannelEngine using the POST /v2/settlements/upload endpoint. Once uploaded, ChannelEngine standardizes the data so you can view and export it in the same way as automatically retrieved settlements.

Endpoint: upload a settlement file

• Method and path: POST /v2/settlements/upload

Include the channelId query parameter in the call and attach the settlement file in the request body.

Common issues

Next steps

For more information on settlements and related workflows, check out the following resources:

• ChannelEngine: settlement reports - view, export, and upload settlements via the web interface.
• ChannelEngine: settlement export and customization - set up custom settlement report formats and FTP exports.
• Merchant API: main resources - an overview of all main Merchant API resources and endpoints.
• ChannelEngine: API references - access the full interactive Merchant API reference in Scalar.