find_movers
Find the entities (SKUs by default) whose value moved the most for a metric between a period and a baseline. Use direction="down" to surface the biggest losers. This answers "which SKUs lost the most sales"; with tags (ids from list_tags) it ranks inside a brand or any tagged set. A metric of Amazon's S&S report is ranked only between two complete periods, past Amazon's delay and with S&S data every day: otherwise the answer has no rows, and notRanked and subscribeAndSaveNotice say why. 🧾 COST CATEGORIES: every cost has one of four categories (variable, product, oneOff, account; costCategory in list_metrics / describe_metric, and the totals orderCosts "Variable costs", productCosts, oneOffCosts, accountCosts). To compare products on their recurring economics, pass costCategories rather than subtracting lines yourself: the response then carries costCategories (what was counted) and costCategoriesNote, which you MUST relay, since the figures are no longer the P&L the app shows by default. 💱 CURRENCY: monetary values are served in the caller's Nova display currency when it is one of the organization's configured currencies (its primary or up to four secondary currencies), else in the organization's primary. In the response, currency is the code, currencyBasis says why (user_preference | organization | pinned) and currencyNotice, when present, MUST be relayed to the user. Quote the code; never assume a symbol from the marketplace. Pass currency to pin any configured code — e.g. to reproduce a figure the seller read on a dashboard set to another currency. 🏷️ 3P / 1P: an Amazon account sells through ONE programme: Seller Central (3P, channel SELLER: the seller sells its products to Amazon's customers) or Vendor Central (1P, channel VENDOR: Amazon BUYS the products from the vendor and resells them itself). On a Vendor Central read, the basis of units, sales and netSales is the answer's vendorTopLineNetReceived (said in its channelNote): when it is 1, units and sales of a Vendor Central row are Amazon's net received (what Amazon received from the vendor, net of what it returned, at its cost, on the day of the receipt: the Net received of the Vendor Central console) and netSales the net received less the quick-pay and early-payment discounts; what the vendor invoiced reads in vendorInvoiced; when it is 0, units and sales are what the vendor invoiced Amazon (its books, at the invoice date) and netSales the invoiced amount less Amazon's claims; Amazon's shelf (what it shipped to its customers, at its retail price, the latest days provisional, on ordered units) is read with vendorShippedUnits, vendorShippedRevenue and vendorShippedCogs. A vendor's profit is netProfit, the P&L's Net Profit: the P&L's top line (Amazon's net received when the answer's vendorTopLineNetReceived is 1, what the vendor invoiced Amazon when it is 0) less what Amazon takes off (its claims on the invoices, the discounts, the co-op, the chargebacks, the returns to vendor), the product cost and the ad spend. vendorShelfProfit is the result on what Amazon shipped, at the ship date: Amazon's shelf, the figure to compare products on, never added to the P&L. channel in list_accounts says which programme each account sells through. A call reads Seller Central, unless you pass channels=['VENDOR'] (do so only when the user asks about Vendor Central / 1P), the accounts of the call are all Vendor Central accounts, or you pass channels=['SELLER','VENDOR'] for All channels (when the user asks for the total across both programmes): Nova then reads both together as the app's All channels reading does, adding the seller's sales and the vendor's P&L top line. NEVER add 3P and 1P figures yourself: ask for All channels, or make one call per channel and present the two side by side, labelled 3P and 1P. When your scope holds a Vendor Central account the response says which channel it read ('SELLER', 'VENDOR' or 'ALL'), and channelNote what it read and what it left out; a metric the channel does not report (sessions, buy box, promotions on Vendor Central) comes back null with an unservedMetrics note, never 0.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Period end, INCLUSIVE (YYYY-MM-DD): a calendar month is from=YYYY-MM-01 to=its LAST day. to=the 1st of the next month adds one extra day to every total (and one extra bucket with a time grain). | |
| from | Yes | Period start, INCLUSIVE (YYYY-MM-DD). | |
| tags | No | "Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations) — a tag NAME is rejected. Tags of one drawer OR together, tags of different drawers AND together (the dashboard rule). | |
| limit | No | ||
| metric | Yes | A single metric key, e.g. "netSales" or "units" (natural names that mean exactly one metric are accepted too). | |
| reason | No | One sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used. | |
| accounts | No | Restrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id. | |
| channels | No | The Amazon programme the call reads. 'SELLER' = Seller Central (3P): the seller's own sales to Amazon's customers. 'VENDOR' = Vendor Central (1P): Amazon buys the products from the vendor and resells them. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR. Pass ['VENDOR'] only when the user asks for Vendor Central / 1P figures. Pass ['SELLER','VENDOR'] for All channels, when the user asks for the total across both programmes: Nova reads them together as the app's All channels reading does, adding the seller's sales and the vendor's top line (Amazon's net received when the answer's vendorTopLineNetReceived is 1, what the vendor invoiced Amazon when it is 0), while a metric one programme measures stays that programme's figure. | |
| currency | No | Pin the reporting currency: one of the organization's configured codes — its primary or any of its secondary currencies (e.g. "USD"). Omit to follow the caller's Nova display currency, the dashboard's rule. Any other code is refused. | |
| dimension | No | What to rank. Defaults to sku. | |
| direction | No | down = biggest losers (default), up = biggest gainers. | |
| comparisonTo | Yes | Baseline period end (inclusive). | |
| comparisonFrom | Yes | Baseline period start (inclusive). | |
| costCategories | No | The cost categories the figures COUNT. Omit for every cost (the default, the P&L as the app shows it). "variable" = triggered by a unit sold or returned: cost of goods, FBM cost, referral and closing fees, FBA fulfillment, refund costs. "product" = keeping the product in stock and replenished: storage, long-term storage, inbound transportation and placement, prep. "oneOff" = a decision or a correction on the product: removals, disposals, deals and coupons, Vine, inventory reimbursements and clawbacks. "account" = billed to the account whatever the products: subscription, paid services, EPR. A category left out reads 0 on its own lines and is out of every total (totalAmazonFees, grossProfit, netProfit, the margins); sales, units and advertising never move. PROFIT WITHOUT ONE-OFFS = netProfit with costCategories ["variable","product","account"]; the profit on unavoidable costs alone = ["variable"]. One-offs are often a net CREDIT (reimbursements), so a profit without them can be lower than net profit. |