Skip to main content
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.
  • 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. 
curl -X POST "https://mm-api.merchantspring.io/channels" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Each channel in the response includes the merchantId and channelId you’ll pass to other endpoints. See the full schema and filter options 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: 
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: 
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: 
{
  "reportId": "YOUR_REPORT_ID",
  "reportType": "salesByProduct",
  "status": "done",
  "downloadUrl": "https://.../report.csv"
}
The full create → status → download flow (and which reports also offer instant JSON view endpoints) is covered in the Reports guide.

​
Next steps

Reports guide

The full report lifecycle and the list of available reports.

API Reference

Every endpoint, with an interactive playground.

Profitability

Store and product P&L, and managing unit COGS.

Conventions

Pagination, dates, and error handling.