# MerchantSpring Public API ## Docs - [Retrieve a list of channels](https://docs.merchantspring.io/api-reference/channel/retrieve-a-list-of-channels.md): Retrieve a list of channels that match the specified filter criteria - [Retrieve a list of content changes](https://docs.merchantspring.io/api-reference/content-change/retrieve-a-list-of-content-changes.md): 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](https://docs.merchantspring.io/api-reference/custom-group/create-a-custom-group.md): Create a new custom product group for a channel. - [Delete a custom group](https://docs.merchantspring.io/api-reference/custom-group/delete-a-custom-group.md): Delete a custom product group for a channel. - [Retrieve a single custom group](https://docs.merchantspring.io/api-reference/custom-group/retrieve-a-single-custom-group.md): Retrieve a single custom group with its associated products and brands. - [Retrieve custom groups for a channel](https://docs.merchantspring.io/api-reference/custom-group/retrieve-custom-groups-for-a-channel.md): Retrieve the list of custom product groups defined for a given channel. - [Update a custom group](https://docs.merchantspring.io/api-reference/custom-group/update-a-custom-group.md): 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)](https://docs.merchantspring.io/api-reference/order/retrieve-a-list-of-orders-for-an-amazon-channel-requires-enterprise-plan.md): Retrieve a list of orders for an Amazon channel that match the specified filter criteria. - [Get a store profit and loss](https://docs.merchantspring.io/api-reference/profitability/get-a-store-profit-and-loss.md): Get a "store profit and loss" - [Get the status of a Unit COGS update job](https://docs.merchantspring.io/api-reference/profitability/get-the-status-of-a-unit-cogs-update-job.md): Get the status of a Unit COGS update job - [Retrieve single or multiple product profit and loss details](https://docs.merchantspring.io/api-reference/profitability/retrieve-single-or-multiple-product-profit-and-loss-details.md): Retrieve single or multiple product profit and loss details - [Update Unit COGS](https://docs.merchantspring.io/api-reference/profitability/update-unit-cogs.md): Update Unit COGS - [Create a campaigns report](https://docs.merchantspring.io/api-reference/report/create-a-campaigns-report.md): 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 `C… - [Create a cancellations and refunds report](https://docs.merchantspring.io/api-reference/report/create-a-cancellations-and-refunds-report.md): 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}… - [Create a channel profit and loss report](https://docs.merchantspring.io/api-reference/report/create-a-channel-profit-and-loss-report.md): 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… - [Create a customer lifetime value report](https://docs.merchantspring.io/api-reference/report/create-a-customer-lifetime-value-report.md): 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… - [Create a inventory health report](https://docs.merchantspring.io/api-reference/report/create-a-inventory-health-report.md): 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… - [Create a inventory replenishment report](https://docs.merchantspring.io/api-reference/report/create-a-inventory-replenishment-report.md): 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… - [Create a marketing by product report](https://docs.merchantspring.io/api-reference/report/create-a-marketing-by-product-report.md): 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… - [Create a ordered revenue report](https://docs.merchantspring.io/api-reference/report/create-a-ordered-revenue-report.md): 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)](https://docs.merchantspring.io/api-reference/report/create-a-products-report-requires-enterprise-plan.md): 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. - [Create a repeat purchase report](https://docs.merchantspring.io/api-reference/report/create-a-repeat-purchase-report.md): 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 th… - [Create a sales by product report](https://docs.merchantspring.io/api-reference/report/create-a-sales-by-product-report.md): 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 stat… - [Create a shipped revenue report](https://docs.merchantspring.io/api-reference/report/create-a-shipped-revenue-report.md): 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 t… - [Create a subscribe and save report](https://docs.merchantspring.io/api-reference/report/create-a-subscribe-and-save-report.md): 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… - [Create a suppressed product report](https://docs.merchantspring.io/api-reference/report/create-a-suppressed-product-report.md): 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 d… - [Create a traffic and conversion report](https://docs.merchantspring.io/api-reference/report/create-a-traffic-and-conversion-report.md): 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 s… - [Create an Amazon Buy Box Performance Report report](https://docs.merchantspring.io/api-reference/report/create-an-amazon-buy-box-performance-report-report.md): 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. Us… - [Get the status of a report request](https://docs.merchantspring.io/api-reference/report/get-the-status-of-a-report-request.md): Get the status of a report request - [Retrieve sales-by-period performance](https://docs.merchantspring.io/api-reference/report/retrieve-sales-by-period-performance.md): 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](https://docs.merchantspring.io/api-reference/report/retrieve-vendor-sales-by-period-performance.md): Retrieve aggregated revenue with advertising metrics for a merchant over the selected date range, grouped by the requested interval. - [View advertising performance by channel](https://docs.merchantspring.io/api-reference/report/view-advertising-performance-by-channel.md): 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](https://docs.merchantspring.io/api-reference/report/view-sales-by-channel-report.md): View sales by channel report - [View sales by product report](https://docs.merchantspring.io/api-reference/report/view-sales-by-product-report.md): View sales by product report as JSON - [Add and/or remove tags on a specific channel](https://docs.merchantspring.io/api-reference/tag/add-andor-remove-tags-on-a-specific-channel.md): 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… - [Convert a tag between private and shared](https://docs.merchantspring.io/api-reference/tag/convert-a-tag-between-private-and-shared.md): 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](https://docs.merchantspring.io/api-reference/tag/retrieve-all-tags.md): 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](https://docs.merchantspring.io/api-reference/tag/retrieve-tags-from-a-specific-channel.md): 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. - [Authentication](https://docs.merchantspring.io/authentication.md): How to authenticate with the MerchantSpring Public API using your API key. - [Conventions](https://docs.merchantspring.io/guides/conventions.md): Shared conventions across the API: requests, pagination, dates, and errors. - [Profitability](https://docs.merchantspring.io/guides/profitability.md): Retrieve store and product profit & loss, and manage unit COGS. - [Reports](https://docs.merchantspring.io/guides/reports.md): How to create, poll, and download reports — and which reports are available. - [Introduction](https://docs.merchantspring.io/introduction.md): Welcome to the MerchantSpring API — programmatic access to all your marketplace operations. - [Quickstart](https://docs.merchantspring.io/quickstart.md): Make your first call to the MerchantSpring Public API in a few minutes. ## OpenAPI Specs - [openapi](https://docs.merchantspring.io/api-reference/openapi.json)