> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantspring.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> How to create, poll, and download reports — and which reports are available.

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:

```json theme={null}
{
  "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`:

```bash theme={null}
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](/api-reference/report/create-a-sales-by-product-report) page.

## Step 3 — Poll for status

Call [`GET /reports/status/{reportId}`](/api-reference/report/get-the-status-of-a-report-request) until the report is finished:

```json theme={null}
{ 
  "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**.

```json theme={null}
{
  "reportId": "<reportId>",
  "reportType": "<reportType>",
  "status": "done",
  "downloadUrl": "https://.../report.csv"
}
```