# Retrieve multi-channel advertising ad group performance Source: https://docs.merchantspring.io/api-reference/advertising/retrieve-multi-channel-advertising-ad-group-performance /api-reference/openapi.json get /advertising/adGroups Returns paginated advertising ad group performance across up to 5 channels for the selected date range, optionally filtered to specific campaigns. Values are currency-adjusted based on each store's country and the requested currency. Supports filtering by ad group status, sorting by any response column, and zero-based page indexing. # Retrieve multi-channel advertising campaign performance Source: https://docs.merchantspring.io/api-reference/advertising/retrieve-multi-channel-advertising-campaign-performance /api-reference/openapi.json get /advertising/campaigns Returns paginated advertising campaign performance across up to 5 channels for the selected date range. Values are currency-adjusted based on each store's country and the requested currency. Supports filtering by campaign status and custom campaign groups, sorting by any response column, and zero-based page indexing. # Retrieve multi-channel advertising keyword performance Source: https://docs.merchantspring.io/api-reference/advertising/retrieve-multi-channel-advertising-keyword-performance /api-reference/openapi.json get /advertising/keywords Returns paginated advertising keyword performance across up to 5 channels for the selected date range, optionally filtered to specific campaigns and ad groups. Values are currency-adjusted based on each store's country and the requested currency. Supports filtering by keyword status, sorting by any response column, and zero-based page indexing. # Retrieve multi-channel advertising product performance Source: https://docs.merchantspring.io/api-reference/advertising/retrieve-multi-channel-advertising-product-performance /api-reference/openapi.json get /advertising/products Returns paginated advertising product (ASIN) performance across up to 5 channels for the selected date range, optionally filtered to specific products. Values are currency-adjusted based on each store's country and the requested currency. Supports sorting by any response column and zero-based page indexing. # Retrieve a list of channels Source: https://docs.merchantspring.io/api-reference/channel/retrieve-a-list-of-channels /api-reference/openapi.json post /channels Retrieve a list of channels that match the specified filter criteria # Retrieve a list of content changes Source: https://docs.merchantspring.io/api-reference/content-change/retrieve-a-list-of-content-changes /api-reference/openapi.json post /content-changes Retrieve a paginated list of product content changes for a given store. Returns one record per product with per-field change status, original value, benchmark value and last-changed timestamp. Page size is capped at 500 items per request. Uses zero-based page indexing (pageIndex starts at 0). # Create a custom group Source: https://docs.merchantspring.io/api-reference/custom-group/create-a-custom-group /api-reference/openapi.json post /customGroups Create a new custom product group for a channel. # Delete a custom group Source: https://docs.merchantspring.io/api-reference/custom-group/delete-a-custom-group /api-reference/openapi.json delete /customGroups/{id} Delete a custom product group for a channel. # Retrieve a single custom group Source: https://docs.merchantspring.io/api-reference/custom-group/retrieve-a-single-custom-group /api-reference/openapi.json get /customGroups/{id} Retrieve a single custom group with its associated products and brands. # Retrieve custom groups for a channel Source: https://docs.merchantspring.io/api-reference/custom-group/retrieve-custom-groups-for-a-channel /api-reference/openapi.json get /customGroups Retrieve the list of custom product groups defined for a given channel. # Update a custom group Source: https://docs.merchantspring.io/api-reference/custom-group/update-a-custom-group /api-reference/openapi.json patch /customGroups/{id} Add or remove products/brands and optionally rename the group. Provide at least one of addProducts, removeProducts, addBrands, removeBrands, or groupName. Cannot mix product and brand operations in the same request. # Retrieve a list of orders for an Amazon channel (Requires Enterprise plan) Source: https://docs.merchantspring.io/api-reference/order/retrieve-a-list-of-orders-for-an-amazon-channel-requires-enterprise-plan /api-reference/openapi.json post /orders/amazon Retrieve a list of orders for an Amazon channel that match the specified filter criteria. **NOTE: This endpoint is only available to users on the Enterprise plan.** # Get a store profit and loss Source: https://docs.merchantspring.io/api-reference/profitability/get-a-store-profit-and-loss /api-reference/openapi.json post /profitability/storeProfitAndLoss Get a "store profit and loss" # Get the status of a Unit COGS update job Source: https://docs.merchantspring.io/api-reference/profitability/get-the-status-of-a-unit-cogs-update-job /api-reference/openapi.json get /profitability/directCostsJobStatus Get the status of a Unit COGS update job # Retrieve single or multiple product profit and loss details Source: https://docs.merchantspring.io/api-reference/profitability/retrieve-single-or-multiple-product-profit-and-loss-details /api-reference/openapi.json post /profitability/productProfitAndLoss Retrieve single or multiple product profit and loss details # Update Unit COGS Source: https://docs.merchantspring.io/api-reference/profitability/update-unit-cogs /api-reference/openapi.json post /profitability/directCosts Update Unit COGS # Create a campaigns report Source: https://docs.merchantspring.io/api-reference/report/create-a-campaigns-report /api-reference/openapi.json post /reports/create/campaigns Create a "campaigns" report (Amazon Advertising). The download contains multiple CSV files: campaigns, ad groups, keywords, product ads, and products. See the `CampaignsReportCampaignColumns`, `CampaignsReportAdGroupColumns`, `CampaignsReportKeywordColumns`, `CampaignsReportProductAdColumns`, and `CampaignsReportProductColumns` schemas for the columns in each file. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a cancellations and refunds report Source: https://docs.merchantspring.io/api-reference/report/create-a-cancellations-and-refunds-report /api-reference/openapi.json post /reports/create/cancellationsAndRefunds Create a "cancellations and refunds" report. The generated report CSV contains the columns defined in the `CancellationsAndRefundsReportColumns` schema. Note that cancelledSales, cancelRate, and their prior period equivalents are hidden for Amazon seller channels. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a channel profit and loss report Source: https://docs.merchantspring.io/api-reference/report/create-a-channel-profit-and-loss-report /api-reference/openapi.json post /reports/create/channelProfitAndLoss Create a "channel profit and loss" report. The generated report CSV contains the columns defined in the `ChannelProfitAndLossReportColumns` schema including revenue, fees, COGS, advertising, and profit breakdown by store. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a customer lifetime value report Source: https://docs.merchantspring.io/api-reference/report/create-a-customer-lifetime-value-report /api-reference/openapi.json post /reports/create/customerLifetimeValue Create a "customer lifetime value" report. The generated report CSV contains the columns defined in the `CustomerLifetimeValueReportColumns` schema including cohort metrics such as LTV, CAC, and repeat purchase frequency. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a inventory health report Source: https://docs.merchantspring.io/api-reference/report/create-a-inventory-health-report /api-reference/openapi.json post /reports/create/inventoryHealth Create an "inventory health" report (Amazon Vendor). The generated report CSV contains the columns defined in the `InventoryHealthReportColumns` schema including sellable, unhealthy, aged, and unsellable inventory metrics. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a inventory replenishment report Source: https://docs.merchantspring.io/api-reference/report/create-a-inventory-replenishment-report /api-reference/openapi.json post /reports/create/inventoryReplenishment Create an "inventory replenishment" report (Amazon FBA). The generated report CSV contains the columns defined in the `InventoryReplenishmentReportColumns` schema including days cover, projected OOS dates, and replenishment recommendations. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a marketing by product report Source: https://docs.merchantspring.io/api-reference/report/create-a-marketing-by-product-report /api-reference/openapi.json post /reports/create/marketingByProduct Create a "marketing by product" report. The generated report CSV contains the columns defined in the `MarketingByProductReportColumns` schema including ad sales, spend, ACOS, ROAS, TACOS, and new-to-brand metrics by store. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a ordered revenue report Source: https://docs.merchantspring.io/api-reference/report/create-a-ordered-revenue-report /api-reference/openapi.json post /reports/create/orderedRevenue Create an "ordered revenue" report (Amazon Vendor). The generated report CSV contains the columns defined in the `OrderedRevenueReportColumns` schema. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a products report (Requires Enterprise plan) Source: https://docs.merchantspring.io/api-reference/report/create-a-products-report-requires-enterprise-plan /api-reference/openapi.json post /reports/create/products Create a "products" report (Amazon). The generated report CSV contains the columns defined in the `ProductsReportColumns` schema including pricing, inventory, COGS, fees, and category information. **NOTE: This endpoint is only available to users on the Enterprise plan.** Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a repeat purchase report Source: https://docs.merchantspring.io/api-reference/report/create-a-repeat-purchase-report /api-reference/openapi.json post /reports/create/repeatPurchase Create a "repeat purchase" report. The generated report CSV contains the columns defined in the `RepeatPurchaseReportColumns` schema including repeat customer counts, sales percentages, and per-customer revenue metrics. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a sales by product report Source: https://docs.merchantspring.io/api-reference/report/create-a-sales-by-product-report /api-reference/openapi.json post /reports/create/salesByProduct Create a "sales by product" report. The generated report CSV contains the columns defined in the `SalesByProductReportColumns` schema. For Amazon Vendor channels, 'totalSales' is replaced by 'poValue' and 'unitsSold' by 'unitsOrdered'. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a shipped revenue report Source: https://docs.merchantspring.io/api-reference/report/create-a-shipped-revenue-report /api-reference/openapi.json post /reports/create/shippedRevenue Create a "shipped revenue" report (Amazon Vendor). The generated report CSV contains the columns defined in the `ShippedRevenueReportColumns` schema. The 'view' option selects between 'sourcing' and 'manufacturing' data. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a subscribe and save report Source: https://docs.merchantspring.io/api-reference/report/create-a-subscribe-and-save-report /api-reference/openapi.json post /reports/create/subscribeAndSave Create a "subscribe and save" report (Amazon). The generated report CSV contains the columns defined in the `SubscribeAndSaveReportColumns` schema including subscriber counts, shipped revenue, revenue penetration, and discount tiers. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a suppressed product report Source: https://docs.merchantspring.io/api-reference/report/create-a-suppressed-product-report /api-reference/openapi.json post /reports/create/suppressedProduct Create a "suppressed product" report. The generated report CSV contains the columns defined in the `SuppressedProductReportColumns` schema including suppression dates, issue types, estimated lost sales, and fix URLs. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create a traffic and conversion report Source: https://docs.merchantspring.io/api-reference/report/create-a-traffic-and-conversion-report /api-reference/openapi.json post /reports/create/trafficAndConversion Create a "traffic and conversion" report. The generated report CSV contains the columns defined in the `TrafficAndConversionReportColumns` schema. When the 'view' option is set to 'skus', additional columns 'sku' and 'brand' are included. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Create an Amazon Buy Box Performance Report report Source: https://docs.merchantspring.io/api-reference/report/create-an-amazon-buy-box-performance-report-report /api-reference/openapi.json post /reports/create/amazonBuyBoxPerformance Create an Amazon Buy Box Performance report. The generated report CSV contains the columns defined in the `AmazonBuyBoxPerformanceReportColumns` schema including your price, competitive price, and detailed offer attributes. An additional 'offerPoints' column is included for Japanese marketplaces. Use the /reports/status/{reportId} endpoint to check report status and obtain the download URL. # Get the status of a report request Source: https://docs.merchantspring.io/api-reference/report/get-the-status-of-a-report-request /api-reference/openapi.json get /reports/status/{reportId} Get the status of a report request # Retrieve sales-by-period performance Source: https://docs.merchantspring.io/api-reference/report/retrieve-sales-by-period-performance /api-reference/openapi.json post /reports/view/salesByPeriod Retrieve aggregated GMV, traffic, and advertising metrics for a merchant over the selected date range, grouped by the requested interval. # Retrieve vendor sales-by-period performance Source: https://docs.merchantspring.io/api-reference/report/retrieve-vendor-sales-by-period-performance /api-reference/openapi.json post /reports/view/vendorSalesByPeriod Retrieve aggregated revenue with advertising metrics for a merchant over the selected date range, grouped by the requested interval. # View advertising performance by channel Source: https://docs.merchantspring.io/api-reference/report/view-advertising-performance-by-channel /api-reference/openapi.json post /reports/view/advertisingByChannels Returns a paginated JSON summary of advertising performance grouped by channel for the selected store and date range. Values are currency-adjusted based on the store's country and the provided currency context. # View sales by channel report Source: https://docs.merchantspring.io/api-reference/report/view-sales-by-channel-report /api-reference/openapi.json post /reports/view/salesByChannel View sales by channel report # View sales by product report Source: https://docs.merchantspring.io/api-reference/report/view-sales-by-product-report /api-reference/openapi.json post /reports/view/salesByProduct View sales by product report as JSON # Add and/or remove tags on a specific channel Source: https://docs.merchantspring.io/api-reference/tag/add-andor-remove-tags-on-a-specific-channel /api-reference/openapi.json patch /tags/channel Partially update the tags on a single channel, identified by channelId and merchantId, by supplying addTags and/or removeTags. At least one of the two must be provided, and a tag cannot appear in both lists. A maximum of 5 tags can be added in a single call. Organisation-wide tags are prefixed with 'org://'. Returns the channel's full tag set after the change. # Convert a tag between private and shared Source: https://docs.merchantspring.io/api-reference/tag/convert-a-tag-between-private-and-shared /api-reference/openapi.json post /tags/convert Toggle a single tag (private/shared) across every channel that carries it. Shared tags are prefixed with 'org://'; converting a private tag makes it 'org://<tag>' and vice versa. Only one tag can be converted per request. Returns the full tag set after the conversion. # Retrieve all tags Source: https://docs.merchantspring.io/api-reference/tag/retrieve-all-tags /api-reference/openapi.json get /tags Retrieve a paginated list of tags across all of the caller's channels. Each item is one channel with its tags. Organisation-wide tags are prefixed with 'org://'. Pagination uses pageIndex/pageSize (zero-based); pageSize defaults to 25 and is capped at 100, pageIndex defaults to 0. # Retrieve tags from a specific channel Source: https://docs.merchantspring.io/api-reference/tag/retrieve-tags-from-a-specific-channel /api-reference/openapi.json get /tags/channel Retrieve the tags for a single channel, identified by channelId and merchantId. Organisation-wide tags are prefixed with 'org://'. A channel with no tags returns an empty tags array. # Retrieve budgets and forecasts (Ad Spend Budget, Sales Budget, Sales Forecast) Source: https://docs.merchantspring.io/api-reference/targets/retrieve-budgets-and-forecasts-ad-spend-budget-sales-budget-sales-forecast /api-reference/openapi.json get /targets Returns the sales budget, sales forecast and ad spend budget targets for a channel over a date range. Data is an ordered array with ISO 8601 and Unix epoch start/end times for each period bucket; the number of buckets depends on interval (for example a one-year range with interval=month returns ~12 buckets, interval=week ~52, interval=day ~366). The totals object is the summed roll-up across the whole range. # Retrieve all vendor fields against an ASIN Source: https://docs.merchantspring.io/api-reference/vendor/retrieve-all-vendor-fields-against-an-asin /api-reference/openapi.json get /vendor/asins Vendor only. Returns one wide row per ASIN combining every data point we hold for the product: catalogue, ordered revenue, shipped revenue (sourcing and manufacturing), inventory health, purchase orders, product profit, sourcing share and advertising. Supply asin to fetch a single product, or omit it to page through the full master list (products with sales activity in the window). The date range must not exceed 30 days. Page size defaults to 20 and is capped at 50 (rows are wide). Uses zero-based page indexing. # Authentication Source: https://docs.merchantspring.io/authentication How to authenticate with the MerchantSpring Public API using your API key. The MerchantSpring Public API uses **API keys** for authentication. Every request must include your key in the `x-api-key` request header. ## Getting your API key API keys are **provisioned automatically by MerchantSpring** — they are not generated from this documentation site. To access your key, you must be an **Owner** or **Administrator** of an organisation that has API access enabled. 1. Sign in to [MerchantSpring](https://mm.merchantspring.io). 2. Go to **Settings → API**. 3. Click the reveal (eye) icon, then copy your key and store it securely — treat it like a password. Each Owner and Administrator has their own individual key. The same page also shows your current plan and API usage. Don't see the **API** tab? It's only visible to Owners and Administrators in organisations with API access enabled. If you are an Owner/Administrator and do not have access, contact MerchantSpring. Keep your API key secret. Never embed it in client-side code, mobile apps, or public repositories. There is no self-service rotation — if a key is exposed, contact MerchantSpring to have it rotated. ## Making authenticated requests Pass your key in the `x-api-key` header on every request: ```bash theme={null} curl -X POST "https://mm-api.merchantspring.io/channels" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` You can also try any endpoint directly from the browser using the **playground** on each API Reference page — paste your key into the `x-api-key` field and press **Send**. ## What your key determines Your key is associated with: * **Your user** — requests return data only for the channels your user can access. * **Endpoint access** — some endpoints require additional access enabled on your key and is available on request — contact MerchantSpring to enable them. ## Error responses | Status | Meaning | | ------ | ----------------------------------------------------------------- | | `400` | Bad request — missing or invalid parameters in the body or query. | | `401` | Valid API key, but it doesn't have access to this endpoint. | | `403` | Missing or invalid API key. | | `404` | The requested resource (e.g. a `reportId`) was not found. | Usage limits (request rate and volume) are governed by the limits attached to your API key. If you need higher limits, talk to your MerchantSpring representative. # Conventions Source: https://docs.merchantspring.io/guides/conventions Shared conventions across the API: requests, pagination, dates, and errors. These conventions apply across the MerchantSpring Public API. ## Format * **HTTPS only.** * Requests and responses are **JSON**. Send `Content-Type: application/json` on requests with a body. * Authenticate with your key in the `x-api-key` header on every request — see [Authentication](/authentication). * Most data endpoints are scoped to a channel by `merchantId` + `channelId`; discover these via [`POST /channels`](/api-reference/channel/retrieve-a-list-of-channels). ## Pagination Paginated endpoints (such as [`POST /content-changes`](/api-reference/content-change/retrieve-a-list-of-content-changes)) use **zero-based** `pageIndex` / `pageSize`: | Parameter | Description | | ----------- | ---------------------------------------------------------------------------------------------- | | `pageIndex` | Page number, starting at `0` (default `0`). | | `pageSize` | Items per page. Defaults and caps vary by endpoint — e.g. content changes are capped at `500`. | Always check the specific endpoint's reference page for its exact defaults and maximum — and where the pagination parameters live, since some endpoints (e.g. content changes) nest `pageIndex` / `pageSize` under a `paginationParams` object. ## Dates Date ranges and timestamps are expressed in the format documented on each endpoint. Provide date-range parameters where an endpoint requires them (for example, the sales-by-period views), and prefer explicit ranges over relying on defaults. ## Reports are asynchronous Report **creation** (`POST /reports/create/*`) returns a `reportId` rather than the data itself. Poll [`GET /reports/status/{reportId}`](/api-reference/report/get-the-status-of-a-report-request) until `status` is `done`, then download the `downloadUrl`. See the [Reports guide](/guides/reports). Endpoints under `/reports/view/*` return JSON immediately and do not need polling. ## Errors The API uses standard HTTP status codes: | Status | Meaning | | ------ | ---------------------------------------------------------- | | `400` | Bad request — missing or invalid parameters. | | `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`). | Error responses include a message describing the problem. # Profitability Source: https://docs.merchantspring.io/guides/profitability Retrieve store and product profit & loss, and manage unit COGS. The Profitability endpoints return profit & loss (P\&L) data and let you manage the unit cost of goods sold (COGS) that feeds those calculations. ## Profit & loss Store P\&L: * [`POST /profitability/storeProfitAndLoss`](/api-reference/profitability/get-a-store-profit-and-loss) — a store-level P\&L: total revenue, total expenses, and the cost breakdown (fees, COGS, advertising). Product P\&L: * [`POST /profitability/productProfitAndLoss`](/api-reference/profitability/retrieve-single-or-multiple-product-profit-and-loss-details) — P\&L for one or more products. See each endpoint's reference page for the exact request body and response schema. ## Managing unit COGS Runs as an **asynchronous job** — submit the update, then poll for completion. [`POST /profitability/directCosts`](/api-reference/profitability/update-unit-cogs) — submit the unit COGS to update. The response identifies the job. [`GET /profitability/directCostsJobStatus`](/api-reference/profitability/get-the-status-of-a-unit-cogs-update-job) — check the status until the job is complete. ```bash theme={null} # 1. Submit the COGS update curl -X POST "https://mm-api.merchantspring.io/profitability/directCosts" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channelId": "YOUR_CHANNEL_ID", "merchantId": "YOUR_MERCHANT_ID", "fromDate": 0, "directCosts": [ { "sellerSku": "string", "cogs": 0, "cogsCurrency": "string", "shippingCost": 0, "shippingCostCurrency": "string" } ] }' # 2. Poll for completion — use the jobId from step 1; repeat until jobStatus is COMPLETED or FAILED curl -X GET "https://mm-api.merchantspring.io/profitability/directCostsJobStatus?merchantId=YOUR_MERCHANT_ID&channelId=YOUR_CHANNEL_ID&jobId=YOUR_JOB_ID" \ -H "x-api-key: YOUR_API_KEY" ``` Updated COGS values are reflected in subsequent profitability and channel-profit-and-loss results once the job completes. # Reports Source: https://docs.merchantspring.io/guides/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": "", "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/`. 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": "", "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": "", "reportType": "", "status": "done", "downloadUrl": "https://.../report.csv" } ``` # Single Sign-On (SSO) Source: https://docs.merchantspring.io/guides/sso The MerchantSpring Single Sign-On is designed to be used by other software companies that want to integrate with MerchantSpring, allowing their clients to sign-on to MerchantSpring without a username and password. For the purpose of this documentation we will refer to the software company as PartyA. ### How it works 1. PartyA uses their private key to sign the JWT. The JWT payload contains user information such as email, user id, company, first name and last name etc (Payload can be customised accordingly) 2. PartyA opens a new window to a GET endpoint. The encoded JWT token and source is passed as a query string param (e.g., `https://analytics.PartyA.com/api/partner/PartyA/auth?source=PartyA&token=eyJh..`). 3. MerchantSpring verifies the validity of the encoded JWT token. * If not valid, return custom HTML error page with response status 401. * If valid: * Check to see whether email address (in JWT payload) already exists in our system: * If it doesn't, provision the user, then log the user in * If it does, check that the user has been originally provisioned via PartyA, and then log the user in * Redirect to dashboard (`https://analytics.PartyAmarketing.com`), and set cookie with encoded JWT token * Note: PartyA can't set cookie directly, since they are on a different domain * Once channel connection is completed and "return to PartyA" is clicked, the user will be redirected to the PartyA platform. PartyA will need to provide MerchantSpring the URL to redirect the user. ### Payload The payload for the JWT token must contain the following fields: * `sub` – a stable user identifier that uniquely identifies a user. An email address is typically not sufficient for this field, since the email address can be updated by the user. * `email` – the email address for the user * `firstName` – the first name for the user * `lastName` – the last name for the user * `iat` – the "Issued At" time of this JWT token, represented as seconds since Unix epoch. JWT verification will fail if the `iat` value exceeds a maximum age of 10 minutes (for GET endpoints) or 1 minute (for DELETE endpoints). * `iss` – the "Issuer" of this JWT token, must be "PartyA". JWT verification will fail if this value is not "PartyA". ```json theme={null} { "sub": "1234567890", "email": "johndoe@example.com", "firstName": "John", "lastName": "Doe", "iat": 1516239022, "iss": "PartyA" } ``` ### New User Provisioning Flow Identical to Single Sign-On Flow ### User Deprovisioning Flow 1. PartyA uses their private key to sign the JWT. The JWT payload contains user information such as email, first name and last name. 2. PartyA submits the JWT token to a DELETE endpoint. The encoded JWT token and source are passed as the DELETE body (e.g., `https://analytics.PartyA.com/api/partner/PartyA/auth`). 3. MerchantSpring verifies the validity of the encoded JWT token. * If not valid, return response status 401. * If valid: * Check to see whether email address (in JWT payload) already exists in our system: * If it does not, return response status 400 * If it does, flag the user for deletion * If successful, return response status 200 * If not successful, return response status 500 ## Webhook to receive API key The webhook process is required when PartyA wishes to retrieve data about their provisioned user. ### How it works When a new user is provisioned, an API key is generated for the user. This API key can be used to make calls to endpoints on our API Gateway. The API key will be sent via a POST request to a webhook URL provided by PartyA. The payload in the request will contain the following data: ```js theme={null} { //email address of the user provisioned email: "john.doe@merchantspring.io", apiKey: "apiKeyForTheUser", //matching the externalUserId that is sent in the sub of the sign in payload externalUserId: "externalUserId1" } ``` # Introduction Source: https://docs.merchantspring.io/introduction Welcome to the MerchantSpring API — programmatic access to all your marketplace operations.

Operate every marketplace from one API.

One REST API for orders, channels, content changes, and performance reports across every connected marketplace.

curl
120+
Marketplaces
REST
JSON API
x-api-key
Simple auth
MCP
Agent-ready
## What you can build Retrieve, update, and fulfil orders across all your connected marketplaces through a single, unified endpoint. Keep stock levels accurate and in sync across Amazon, eBay, Shopify, and more — in real time. Access sales analytics, profit reports, and marketplace metrics to power your own dashboards and tools. Create, update, and optimise product listings across every marketplace channel programmatically. ## How it works Get your API key from **Settings → API** in [MerchantSpring](https://mm.merchantspring.io) and pass it in the `x-api-key` header on every request. Browse the [API Reference](/api-reference/channel/retrieve-a-list-of-channels) to find the endpoint you need — orders, inventory, listings, analytics, and more. Follow the [Quickstart](/quickstart) guide to make your first live API request in under 5 minutes. ## Need help? Start with authentication then follow the quickstart guide. Can't find what you need? Our team is happy to help. # Quickstart Source: https://docs.merchantspring.io/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. ```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()); ``` 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" } ``` The full create → status → download flow (and which reports also offer instant JSON `view` endpoints) is covered in the [Reports guide](/guides/reports). ## Next steps The full report lifecycle and the list of available reports. Every endpoint, with an interactive playground. Store and product P\&L, and managing unit COGS. Pagination, dates, and error handling.