Reports

The Reporting API is the core of the MerchantSpring Public API. Reports are generated asynchronously: you create a report, poll its status, and download the result when it’s ready. Some reports also offer instant JSON views.

Step 1 — Identify the channel

Many of our endpoints require you to provide two MerchantSpring channel identifiers - merchantId & channelId. In order to know what these parameters are we provide a /channels endpoint at the first point of contact for all report requests. The response from the channels endpoint will looks like the following:

{
  "channelId": "<channelId>",
  "merchantId": "<merchantId>",
  "marketplace": "amazon",
  "countryCode": "USA",
  "displayName": "Your Shop Name",
  "hasAdvertisingConnected": true
}

You can use the displayName and countryCode to identify the record you wish to request data for.

Step 2 — Create a report

Create a report by calling POST /reports/create/<reportName>. The call returns a reportId:

curl -X POST "https://mm-api.merchantspring.io/reports/create/salesByProduct" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "merchantId": "YOUR_MERCHANT_ID", "channelId": "YOUR_CHANNEL_ID" }'

Each report’s exact request body (date ranges, view options, columns) is documented on its API Reference page.

Step 3 — Poll for status

Call GET /reports/status/{reportId} until the report is finished:

{ 
  "reportId": "<reportId>",
  "reportType": "<reportType>",
  "status": "inProgress" 
}

The status field moves through started → inProgress → done (or errored if it fails).

Step 4 — Download

When status is done, the response includes a downloadUrl. Open it (or fetch it) to retrieve the report — reports are delivered as CSV.

{
  "reportId": "<reportId>",
  "reportType": "<reportType>",
  "status": "done",
  "downloadUrl": "https://.../report.csv"
}

Getting Started

Guides

Step 1 — Identify the channel

Step 2 — Create a report

Step 3 — Poll for status

Step 4 — Download

​Step 1 — Identify the channel

​Step 2 — Create a report

​Step 3 — Poll for status

​Step 4 — Download

Step 1 — Identify the channel

Step 2 — Create a report

Step 3 — Poll for status

Step 4 — Download