> ## 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.

# Quickstart

> Make your first call to the MerchantSpring Public API in a few minutes.

This guide walks you through your first calls to the MerchantSpring Public API: finding your channels, then requesting a report.

## Prerequisites

* An **API key** issued by MerchantSpring — see [Authentication](/authentication).
* `curl` or any HTTP client.

## Step 1 — Find your channels

Most endpoints identify a channel by two values: `merchantId` and `channelId`. Call `POST /channels` to list the channels your organisation can access.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://mm-api.merchantspring.io/channels" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://mm-api.merchantspring.io/channels",
      headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json={},
  )
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://mm-api.merchantspring.io/channels", {
    method: "POST",
    headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({}),
  });
  console.log(await resp.json());
  ```
</CodeGroup>

Each channel in the response includes the `merchantId` and `channelId` you'll pass to other endpoints. See the [full schema and filter options](/api-reference/channel/retrieve-a-list-of-channels) on the endpoint reference page.

## Step 2 — Request a report

Reports are generated asynchronously. You **create** a report, then **poll** for its status until a download URL is ready. For example, create a "sales by product" report:

```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" }'
```

The response returns a `reportId`.

## Step 3 — Poll for the report

Check the status with the `reportId`:

```bash theme={null}
curl -X GET "https://mm-api.merchantspring.io/reports/status/YOUR_REPORT_ID?merchantId=YOUR_MERCHANT_ID&channelId=YOUR_CHANNEL_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

While processing, `status` is `started` or `inProgress`. It ends as `done` — which includes a `downloadUrl` to the CSV — or `errored` if it failed:

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

<Tip>
  The full create → status → download flow (and which reports also offer instant JSON `view` endpoints) is covered in the [Reports guide](/guides/reports).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Reports guide" icon="file-lines" href="/guides/reports">
    The full report lifecycle and the list of available reports.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/channel/retrieve-a-list-of-channels">
    Every endpoint, with an interactive playground.
  </Card>

  <Card title="Profitability" icon="coins" href="/guides/profitability">
    Store and product P\&L, and managing unit COGS.
  </Card>

  <Card title="Conventions" icon="list-check" href="/guides/conventions">
    Pagination, dates, and error handling.
  </Card>
</CardGroup>