sellerfox

Returns product catalog entries — ASINs, parent/child relationships, names, marketplace, and SKUs. Two modes: free-text discovery via `searchText` (matches name, ASIN, parentAsin, SKU), or batch metadata hydration via `asinMarketplaces[]` (look up the exact catalog rows for a known list of {asin, marketplaceCode} tuples). Pair `asin` with `marketplaceCode` to identify a single listing for downstream tools that take `asinMarketplaces[]`. USE THIS FOR: "what products do I have", "find product B07XYZ1234", "look up the product for SKU X", "hydrate names/images for these {asin, marketplaceCode} tuples I already have". IMPORTANT: The same ASIN on multiple marketplaces is multiple distinct products — pair `asin` with `marketplaceCode`. Supply `searchText` OR `asinMarketplaces[]`, not both; `asinMarketplaces[]` and `marketplaceCodes[]` are also mutually exclusive (tuples already include a marketplace), and `asinMarketplaces[]` matches listings 1:1 with no parent/child family expansion (tuples that do not map to a product are silently omitted). For listing issues use list_events with eventCategories ["listings-item-issues-change-event"]; for KPI numbers use get_product_kpis. Soft-deleted products are excluded by default; pass includeDeleted to include them. Returns: Product list with id, asin, parentAsin, isParent, name, marketplaceCode, mainImage, and SKUs. Filterable by searchText, asinMarketplaces, marketplaceCodes, and includeDeleted.

Returns the ASINs that rank for one tracked keyword on one marketplace, with their product KPI snapshot over a date range. USE THIS FOR: "for keyword X, which of my products rank and how do they perform", "how do my products that target keyword Y compare on revenue and units sold", "which ASINs win the keyword <phrase> on DE". IMPORTANT: The keyword is the free-text LABEL a shopper types (NOT an ObjectId), matched case-insensitively against keywords already tracked in this workspace — if the lookup returns "Keyword not found", the user must add it to keyword tracking first. This tool returns sales and traffic KPIs per ASIN, not rankings. For keyword rank history or rank KPIs use get_keyword_trends or get_keyword_kpis; their ranks are averages across the whole product family, so there is no per-ASIN rank. Date ranges are capped at 730 days. Returns: One row per ranking ASIN with name, brand, mainImage, marketplaceCode, and KPI values. Response uses the English KPI label (e.g. "Units Ordered") as the JSON key, not the code; pass codes from get_kpi_definitions in input fields. If `meta.warnings` is present, the workspace has a data problem that affects the KPIs you just asked for — a history import still running, a disconnected Amazon account, or an expired connection. Read the warning and qualify your answer instead of presenting these figures as final. Call get_workspace_info for the full readiness picture.

Brand-level SQPR is disabled because report data is unavailable. Brand SQPR KPI codes cannot be requested; ASIN SQPR and general search-query metrics remain available. Returns the ASINs that show up under one Amazon search query on one marketplace, with their SQPR KPI snapshot over a date range. USE THIS FOR: "for search query <phrase>, how do my products perform", "which of my ASINs win the search query <phrase> on DE", "which products convert best for the search term <phrase>". IMPORTANT: The searchQuery is the free-text phrase a shopper typed (NOT an ObjectId), matched exactly against the Amazon SQPR report. Granularity is required and restricted to "weekly" or "monthly" — Amazon does not publish SQPR data daily. The kpis array must use SQPR keys; standard product KPIs from the "sales" or "ads-*" categories are not valid here. For SQPR metrics at the query level across many queries, use get_sqpr_kpis instead. Date ranges are capped at 730 days. Returns: One row per ASIN with name, brand, mainImage, marketplaceCode, and KPI values. Response uses the English KPI label (e.g. "Search Query Impressions") as the JSON key, not the code; pass codes from get_kpi_definitions in input fields. `meta.effectiveDateRange` is the range actually queried: Amazon publishes SQPR per whole week or month, so the requested range is widened to whole report periods. Quote that range, not the one you asked for.

Breaks down the expandable profit categories into their detailed components: gross revenue, refunds, referral fees, FBA fees, other Amazon fees, shipping, gift wrap, advertising, and other costs. It uses the same calculations as the profit dashboard. USE THIS FOR: "show my profit cost breakdown", "which Amazon fees make up my costs", "what is inside my refund or advertising costs". To answer "why is my margin down" or to explain the difference between revenue and profit, call this tool together with get_profit_summary. IMPORTANT: from and to are timestamps in the user's local time with the correct UTC offset, not dates, covering whole local days (00:00:00 to 23:59:59); see the field descriptions. This tool returns only the expandable categories listed above. COGS and the revenue and profit subtotals never appear in it. VAT and promotions appear only when part of them is estimated for pending orders Amazon has not priced yet; they are then split into a from-Amazon child and an estimated child. Use get_profit_summary for COGS, VAT and the revenue-to-profit totals, and combine both tools to explain a margin. Only an unfiltered, ungrouped profit summary carries the full account cost scope. SKU rows cannot state ad spend: profitAdSpend, profitDb3 and profitNetProfit are null per SKU; profitDb2 is the available bottom line at that grain. Product filters exclude costs that cannot be attributed to the selected products, including account-level and marketplace-level costs. An explicit marketplace filter also excludes overall user-entered costs. Grouped rows may not sum to the summary: preserve dataUnassigned and use the grand total instead of summing rows. Check meta.isComplete, meta.unattributableKpis and meta.hasProductFilter before stating a total. isComplete describes cost attribution only, not report coverage or whether COGS and other cost settings are maintained; these are not verified. Profit KPIs include overlapping subtotals and fee components, so do not add all KPI columns together; use profitNetProfit for net profit and get_profit_breakdown for the cost composition. Refunds use period basis. No comparison period is provided. Parent totals and their children use the same dashboard calculation. isCredit describes the direction of a child; credit children add to revenue and offset costs. Child percentages are signed shares of net revenue, or null when net revenue is zero or negative (for example a product filter whose refunds exceed its sales). The remainder is already represented by a remainder child where applicable; do not add it again. Raw Amazon fee types and user categories have descriptive labels but no catalog code. Date ranges are capped at 730 days. Returns: A data object keyed by English parent labels. Each parent has children, remainder, and total. Children have label, value, isCredit, percentage, and code only when the child is a catalog KPI. Meta includes currency, dateRange (the from and to timestamps as sent), period refund basis, cost attribution completeness, and available warnings.

Returns profit KPIs ranked by SKU, child ASIN, parent ASIN or marketplace using the dashboard profit overview. USE THIS FOR: "which SKU loses money", "profit by product", "compare marketplace profitability". Use get_profit_summary for account totals and get_profit_breakdown for cost categories. IMPORTANT: from and to are timestamps in the user's local time with the correct UTC offset, not dates, covering whole local days (00:00:00 to 23:59:59); see the field descriptions. Only an unfiltered, ungrouped profit summary carries the full account cost scope. SKU rows cannot state ad spend: profitAdSpend, profitDb3 and profitNetProfit are null per SKU; profitDb2 is the available bottom line at that grain. Product filters exclude costs that cannot be attributed to the selected products, including account-level and marketplace-level costs. An explicit marketplace filter also excludes overall user-entered costs. Grouped rows may not sum to the summary: preserve dataUnassigned and use the grand total instead of summing rows. Check meta.isComplete, meta.unattributableKpis and meta.hasProductFilter before stating a total. isComplete describes cost attribution only, not report coverage or whether COGS and other cost settings are maintained; these are not verified. Profit KPIs include overlapping subtotals and fee components, so do not add all KPI columns together; use profitNetProfit for net profit and get_profit_breakdown for the cost composition. Refunds use period basis. No comparison period is provided. Returns: data contains grouped identities (ASIN, SKU, ISO marketplace code where applicable), kpis and signed percentages of net revenue, both keyed by English KPI labels; totalRow contains the grand total across all matching pages. dataUnassigned retains costs no detail row can claim. Do not add the residual to totalRow: it is already included. Meta includes pagination, sortBy as an input KPI code, groupBy, attribution completeness and warnings. Product-family filters include children; implicit denominator columns are omitted unless requested.

Returns account profit, revenue, Amazon fees, COGS, advertising and other costs for an inclusive time range given as ISO 8601 timestamps with a UTC offset (the user's local time), using the same calculations as the profit dashboard. USE THIS FOR: "what did I earn last month", "my total costs", "net profit and margin". For the cost waterfall use get_profit_breakdown; for product ranking use get_profit_by_product. IMPORTANT: from and to are timestamps in the user's local time with the correct UTC offset, not dates, covering whole local days (00:00:00 to 23:59:59); see the field descriptions. Only an unfiltered, ungrouped profit summary carries the full account cost scope. SKU rows cannot state ad spend: profitAdSpend, profitDb3 and profitNetProfit are null per SKU; profitDb2 is the available bottom line at that grain. Product filters exclude costs that cannot be attributed to the selected products, including account-level and marketplace-level costs. An explicit marketplace filter also excludes overall user-entered costs. Grouped rows may not sum to the summary: preserve dataUnassigned and use the grand total instead of summing rows. Check meta.isComplete, meta.unattributableKpis and meta.hasProductFilter before stating a total. isComplete describes cost attribution only, not report coverage or whether COGS and other cost settings are maintained; these are not verified. Profit KPIs include overlapping subtotals and fee components, so do not add all KPI columns together; use profitNetProfit for net profit and get_profit_breakdown for the cost composition. Refunds use period basis. No comparison period is provided. Returns: data is a flat object keyed by English KPI labels; percentages gives the corresponding signed share of net revenue for currency KPIs. Null values remain unknown. Meta includes currencyCode, dateRange (the from and to timestamps as sent), refundBasis, attribution completeness and import warnings. Percentage twins are returned here, not accepted as KPI input columns.

Brand-level SQPR is disabled because report data is unavailable. Brand SQPR KPI codes cannot be requested; ASIN SQPR and general search-query metrics remain available. Returns Amazon Search Query Performance Report metrics at the query level — search volume, impressions, clicks, cart adds, orders, conversion rate, and your share within each metric. USE THIS FOR: "what search queries drive my impressions", "top converting search terms last month", "queries where I lose share to competitors", "search queries that brought traffic to ASIN B07XYZ1234". IMPORTANT: SQPR is only published weekly and monthly — daily granularity is not available. SQPR data only exists at the child-ASIN level (parent ASINs have no SQPR rows). Filter to specific products with `asinMarketplaces[]` tuples; without filters returns the workspace-wide top queries. Use `groupBy: "searchTerm"` (default) for one row per (searchQuery, marketplace) aggregating across all matching child ASINs, or `groupBy: "asin"` to break out one row per (searchQuery, marketplace, asin) — the per-asin view. ASIN-share and ASIN-level absolute KPIs only make sense when a product filter is supplied — without filters, prefer workspace totals and computed rates. For time series use get_sqpr_trends instead. Date ranges are capped at 730 days. Returns: With groupBy="searchTerm" — one row per (searchQuery, marketplaceCode). With groupBy="asin" — one row per (searchQuery, marketplaceCode, asin). Response uses the English KPI label (e.g. "Search Query Impressions") as the JSON key, not the code; pass codes from get_kpi_definitions in input fields. `meta.effectiveDateRange` is the range actually queried: Amazon publishes SQPR per whole week or month, so the requested range is widened to whole report periods. Quote that range, not the one you asked for.

Brand-level SQPR is disabled because report data is unavailable. Brand SQPR KPI codes cannot be requested; ASIN SQPR and general search-query metrics remain available. Returns time-series Amazon Search Query Performance Report metrics, aggregated by week or month. USE THIS FOR: "chart search query volume for term X", "how has my click share trended this quarter", "weekly conversion rate by search query", "graph monthly impressions for queries that touch ASIN B07XYZ1234". IMPORTANT: SQPR granularity is restricted to WEEK or MONTH — daily is not available. SQPR data only exists at the child-ASIN level (parent ASINs have no SQPR rows). Pick one KPI per call; for multi-KPI or aggregated totals use get_sqpr_kpis instead. Filter to products with `asinMarketplaces[]` tuples. Use `groupBy: "searchTerm"` (default) for one series per searchQuery aggregating across all matching child ASINs, or `groupBy: "asin"` to break out one series per (searchQuery, asin) — the per-asin view. ASIN-share and ASIN-level absolute KPIs only make sense when a product filter is supplied. Date ranges are capped at 730 days. Returns: With groupBy="searchTerm" — one row per searchQuery. With groupBy="asin" — one row per (searchQuery, asin). Each row carries a timeSeries array aligned to meta.headerDates. Response meta.kpi carries the English label (e.g. "Search Query Impressions"), not the code; pass the code from get_kpi_definitions in the `kpi` input field. `meta.effectiveDateRange` is the range actually queried: Amazon publishes SQPR per whole week or month, so the requested range is widened to whole report periods. Quote that range, not the one you asked for.

Returns the workspace grounding state: name, currency, current date in UTC, the enabled Amazon marketplaces (ISO code + region), and known connection or import problems. Includes earliest and latest source-report dates observed in ClickHouse per marketplace. Continuous coverage and final attribution are not verified. USE THIS FOR: "what marketplaces does this workspace cover", "what currency are you reporting in", resolving relative date phrases like "last week" or "this month" to ISO dates before calling any date-taking tool, and checking data readiness before you state any figure as fact. IMPORTANT: Call this BEFORE reporting numbers from this workspace, not only for date grounding. A workspace can be mid-import, have an expired Amazon connection, or have no Ads account attached — in all three cases the other tools still return numbers, and those numbers may be incomplete while still looking plausible. The Warnings section tells you which KPI domains (sales, traffic, ads, profit) are affected. The profit domain is affected while the profit history import is still running, and also when the Selling Partner API or Ads API is not connected, the Selling Partner API connection has expired or onboarding is unfinished. If a domain you are about to report on is listed, say so in your answer instead of presenting the figure as final. None of the other tools parse "last 7 days" / "this quarter"; resolve such phrases to explicit dates first. Every tool except the three profit tools takes YYYY-MM-DD dates that are UTC calendar days (Sellerfox supports only UTC days for this data), so do not shift dates to the user's local time; currentDate is today's date in UTC. get_profit_summary, get_profit_breakdown and get_profit_by_product instead take ISO 8601 timestamps in the user's local time with the correct UTC offset, covering whole local days (00:00:00 to 23:59:59). Other tools accept ISO marketplace codes ("de", "us", "gb"), not Amazon internal marketplace IDs. For KPI code meanings call get_kpi_definitions, not this tool. Returns: A markdown text block with workspace name, currency, currentDate (the current date in UTC), enabled marketplaces (each with code and region), a Data Readiness section (Selling Partner API status, Ads API status, and the progress of any history import still running), and a Warnings section listing each data-quality problem with its severity and the KPI domains it affects. structuredContent carries the same facts as workspace, marketplaces, readiness and warnings, plus dataAvailability: the source dates with coverageStatus unverified and nullable firstReportDate/latestReportDate per source and marketplace.

Returns the workspaces this MCP connection can query. The LLM should call this first when the user mentions multiple brands/accounts to discover which workspaceId to pass to other tools. USE THIS FOR: "which brands am I connected to", "list my workspaces", "what accounts can you see", routing a multi-workspace question to the right workspaceId before calling any workspace-scoped tool. IMPORTANT: The returned workspaceId is the value to pass as the workspaceId argument to every other tool. For grounding metadata on a specific workspace (currency, current UTC date, enabled marketplaces) call get_workspace_info with that workspaceId. This tool takes no parameters — eligibility is derived from the current MCP connection. Returns: { data: [{ workspaceId, name, currency }] } — an object with a `data` array of rows for the workspaces this connection is authorized to query.

Returns business events that explain performance changes — buy-box losses, price changes, listing status changes, catalog edits, listing issues, and custom events. USE THIS FOR: "why did my sales drop", "what happened to ASIN B07XYZ1234 around date Y", "show me listing issues this week", "any buy-box losses last month on DE". IMPORTANT: Events overlap a date range if their [startAt, endAt] interval intersects it — a multi-day event that started before the range still appears. Filter by eventCategories[] for specific types (e.g. ["listings-item-issues-change-event"] for listing issues, ["buy-box-lost-event"] for buy-box losses); passing an invalid value returns the full valid list in the error message. Filter to products with asin + marketplaceCode. Date ranges are capped at 730 days. Returns: Event list with date range, affected products, event type, and event-specific log payload. Categorised via the discriminator pattern.

Lists manual and Amazon-derived income and expense entries with their category and allocation scope. USE THIS FOR: "what did I book in July", "show me recurring expenses", "which storage fees did Amazon charge", "find my hosting expenses". IMPORTANT: Only an unfiltered, ungrouped profit summary carries the full account cost scope. SKU rows cannot state ad spend: profitAdSpend, profitDb3 and profitNetProfit are null per SKU; profitDb2 is the available bottom line at that grain. Product filters exclude costs that cannot be attributed to the selected products, including account-level and marketplace-level costs. An explicit marketplace filter also excludes overall user-entered costs. Grouped rows may not sum to the summary: preserve dataUnassigned and use the grand total instead of summing rows. Check meta.isComplete, meta.unattributableKpis and meta.hasProductFilter before stating a total. isComplete describes cost attribution only, not report coverage or whether COGS and other cost settings are maintained; these are not verified. Profit KPIs include overlapping subtotals and fee components, so do not add all KPI columns together; use profitNetProfit for net profit and get_profit_breakdown for the cost composition. Refunds use period basis. No comparison period is provided. This ledger is only one part of profit tracking, so meta.isComplete is always false; use get_profit_summary for totals. Amounts retain each entry's original currency and are positive magnitudes; type identifies income or expense. Omit source to include both manual and Amazon-derived entries. Legacy entries without a source count as user entries. Supply both from and to or omit both. Ledger dates use UTC calendar days, matching the dashboard ledger, and are capped at 730 days. Search text is literal, case-insensitive title matching. Category, transaction, template, product, and entry IDs are never exposed. Returns: A paginated list with date, title, type, net amount, tax, original currency, available category name, source, appliesTo scope, marketplaceCodes when scoped, and isRecurring derived from a recurring template. Missing or deleted categories have no categoryName. Sorting by amount uses signed gross (net + tax), with expenses negative. Meta includes paging, timezone (UTC), optional dateRange, period refund basis, and completeness warnings.