explain_movement
For one SKU, pull the causal signal bundle (traffic, conversion, price, buy box, promotions, ads, rank) for a period vs a baseline, so you can reason about WHY its sales moved. Returns each signal with value, comparison value and variance. 💱 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). | |
| sku | Yes | The SKU to explain. | |
| from | Yes | Period start, INCLUSIVE (YYYY-MM-DD). | |
| 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. | |
| comparisonTo | Yes | Baseline period end (inclusive). | |
| comparisonFrom | Yes | Baseline period start (inclusive). |