Skip to content
English
Go to merchantspring.io
  • There are no suggestions because the search field is empty.

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

The MerchantSpring Public API uses API keys for authentication. Reach out to your Account Manager or support@merchantspring.io to enable the API Gateway in your account.

Step 2: API Keys

Once this is provisioned in your account, you can find your personal API key in your MerchantSpring account by navigating to My Account → Settings → API.

You'll also find "View API documentation" right below your API Key. This will guide you on how to use the API Gateway.

Step 3: Choose your endpoint

Browse the API Reference to find the endpoint you need — orders, inventory, listings, analytics, and more.

3. Make Your First API Call

Follow the Quickstart guide to make your first live API request in under 5 minutes.

4. Generate a Report

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.

Follow the steps in this Reports Guide.


5. Monitor Usage & Limits

Each API key has rate limits and usage quotas, visible on your MerchantSpring Account.

  1. Sign in to MerchantSpring.
  2. Go to Settings → API →API Usage.

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:

Error Cause
400 Invalid parameters (wrong date format, booleans as strings)
401 Valid API key, but it doesn’t have access to the endpoint.
403 Missing or invalid API key
 404 Resource not found (e.g. an unknown reportId).

 

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

Region/City Time Zone Value
Los Angeles PST
New York EST
London GMT
Berlin CET
Tokyo JST
Calcutta IST
Sydney AEST

 

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

Issue What It Means How to Fix
Report not appearing in UI The API returns a downloadable file Use the downloadUrl returned by the API
Report data doesn’t match app Most often a date range or parameter mismatch Verify fromDate/toDate (Epoch) and toggles like includeTax, includeNoSales
400 Bad Request Malformed input Check types and formats for all fields

 

8. Available Reports by Channel Type

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

Report Endpoint Amazon 3P (Seller) Amazon 1P (Vendor) Other Marketplaces (Walmart, eBay, MeLi) E-commerce Channels (Shopify, TikTok Shop)
Amazon Buy Box Performance /reports/create/amazonBuyBoxPerformance ✅ ❌ ❌ ❌
Campaigns /reports/create/campaigns ✅ ✅ ✅ ✅
Cancellations and Refunds /reports/create/cancellationsAndRefunds ✅ ❌ ✅ ✅
Channel Profit and Loss /reports/create/channelProfitAndLoss ✅ ✅ ✅ (some) ✅ (some)
Customer Lifetime Value /reports/create/customerLifetimeValue ✅ (add-on) ✅ (add-on) ✅ (add-on) ✅ (add-on)
Inventory Health /reports/create/inventoryHealth ❌ ✅ ❌ ❌
Inventory Replenishment /reports/create/inventoryReplenishment ✅ ❌ ❌ ❌
Ordered Revenue /reports/create/orderedRevenue ❌ ✅ ❌ ❌
Repeat Purchase /reports/create/repeatPurchase ✅ ❌ ✅ (3P) ✅
Sales by Product /reports/create/salesByProduct ✅ ✅ ✅ ✅
Shipped Revenue /reports/create/shippedRevenue ❌ ✅ ❌ ❌
Subscribe and Save /reports/create/subscribeAndSave ✅ ✅ ❌ ❌
Traffic and Conversion /reports/create/trafficAndConversion ✅ ❌ ✅ (Walmart only) ❌

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
  • Follow the API Documentation
  • Need help? support@merchantspring.io