MerchantSpring API Gateway: Starter Guide

Welcome to the MerchantSpring API Gateway. This guide is designed to help you start using our APIs smoothly, covering account setup, API key activation, making your first call, and troubleshooting common issues.

1. What is the API Gateway?

The MerchantSpring API Gateway is the central hub for accessing all our public-facing APIs—whether for fetching reports, accessing marketplace channels, or integrating eCommerce data. It provides a developer portal to:

• View available APIs
• Subscribe to them
• Use the interactive “Try it Out!” console
• Monitor your API usage
• Access live request and response examples

For support, contact support@merchantspring.io.

2. Access and Setup

Step-by-Step Overview:

Step 1: Get a Developer Account

Contact your MerchantSpring representative to get a developer account. Once created, you’ll receive:

• Access to the API portal
• Your personal API key
• Access to the API playground for testing

Step 2: Link API Key to Your Account (Done by MerchantSpring)

Your API key must be linked to your MerchantSpring account internally by our team. You cannot do this step yourself. Your API key will not work until this step is complete.

{ "message": "Missing configuration entry in apiKeys collection" }

Step 3: Subscribe to an API

Once your key is linked, navigate to the APIs section in the portal and click Subscribe for the APIs you want to use. Until you subscribe, any call will return:

{ "message": "Forbidden" }

3. Make Your First API Call

Here’s an example using the /channels endpoint to fetch the list of available channels.

Example Request

curl --location 'https://mm-api.merchantspring.io/channels' --header 'accept: application/json' --header 'x-api-key: <your-api-key>' --header 'Content-Type: application/json' --data '{}'

Example Response

[
  {
    "channelId": "14294905",
    "merchantId": "XXXXXXXXXXXUS @ ATVPDKIKX0DER",
    "marketplace": "amazon",
    "countryCode": "USA",
    "displayName": "Amazon Seller Demo (USA)",
    "hasAdvertisingConnected": true
  }
]

4. Generate a Report (Example: Sales by Product)

Request

curl --location 'https://mm-api.merchantspring.io/reports/create/salesByProduct' --header 'accept: application/json' --header 'x-api-key: <your-api-key>' --header 'Content-Type: application/json' --data-raw '{ 
  "channelId": "14294905",
  "merchantId": "XXXXXXXXXXXUS @ ATVPDKIKX0DER",
  "reportOptions": {
    "fromDate": 1748736000,
    "toDate": 1751328000,
    "priorFromDate": 1717200000,
    "priorToDate": 1719792000,
    "timezone": "GMT",
    "includeNoSales": true,
    "includeNoInventory": true,
    "includeTax": true
  }
}'

Response - Report Queued

{ 
  "reportId": "f44073bc-54f7-404d-9d53-98f984f98208",
  "reportType": "salesByProduct",
  "status": "started"
}

Poll Status

curl --location 'https://mm-api.merchantspring.io/reports/status/f44073bc-54f7-404d-9d53-98f984f98208' --header 'accept: application/json' --header 'x-api-key: <your-api-key>'

Response - Report Ready

{ 
  "reportId": "f44073bc-54f7-404d-9d53-98f984f98208",
  "reportType": "salesByProduct",
  "status": "done",
  "downloadUrl": "https://marketplace-manager-presignedbucket-production.s3...csv"
}

Download

curl -O "<downloadUrl>"

5. Monitor Usage & Limits

Each API key has rate limits and usage quotas, visible on your Developer Portal dashboard. As usage scales up, contact us to upgrade your access if needed.

6. Key Parameters & Common Pitfalls

• Date fields: Must be in Epoch (Unix) timestamp format.
• Boolean fields: Use true or false, not strings.
• Time zone: Must be a valid abbreviation (e.g., GMT, AEST).
• Compatibility: Some reports only work with certain channel types.

Common error messages:

6A. Time Zone Parameters

The timezone parameter must always be passed as a string value in the API request. Using an invalid value will result in a 400 error.

Common Time Zone Values

Do not pass full city names (e.g., “Los Angeles”) or raw offsets (e.g., “+10:00”). Always use the abbreviation (string).

7. FAQ & Troubleshooting

8. Available Reports by Channel Type

Not all reports are available for every channel type. Use this table to see which reports are supported.

Note: Customer Lifetime Value (LTV) is an add-on and may not be available on all plans. If you call an endpoint not supported for a channel type, the API will return an error.

9. Next Steps

• Retrieve your channelId and merchantId using /channels
• Run your first report with the appropriate endpoint
• If anything looks off, compare your date range (Epoch) and toggles to the dashboard settings
• Need help? support@merchantspring.io