Query the seller's metrics over a period, optionally grouped and compared to a baseline period. groupBy takes EITHER an entity grain (sku, childAsin, parentAsin, marketplace, sellerAccount), OR "tag" with drawer — one row per tag of one of the seller's own "Your Filters" drawers (list_tags): THE way to read sales, profit or any metric per BRAND, CATEGORY or supplier when the seller tagged the catalog —, OR a TIME grain (day, week, month, quarter, year). tags restricts any read to the SKUs carrying the given tags (ids from list_tags). Use a TIME grain to get a whole time series in ONE call — e.g. groupBy="month" from Jul to Jun returns all 12 monthly rows at once; never call this once per month. Entities batch the same way: for MANY SKUs/ASINs, pass the whole list (skus/childAsins/parentAsins) with an entity groupBy and read all the rows from ONE call — never loop one call per SKU or ASIN. Rank rows with sortBy+sortOrder (e.g. the top SKUs by netSales) and keep only rows meeting a threshold with metricFilters (e.g. SKUs with netProfit < 0) — both run server-side, so never fetch everything and filter yourself. Returns rows with value, comparison value and variance, plus the reporting currency. 📣 ADVERTISING TOTALS & HISTORY: this tool ALSO serves advertising at the account, product and period level — adSpend, sponsoredSales, organicSales, sponsoredAcos, sponsoredRoas, sponsoredTacos, impressions, clicks, costPerClick, clickThroughRate (Sponsored Products + Display + Brands, allocated to products) — over the WHOLE ads history Nova holds for each account: from about 60 days before its Ads connection, complete from there (NOT a rolling 60-day window; adsHistory + adsHistoryNotice give the first day per account when a requested period starts earlier). Use THIS tool for ad totals, trends and year-over-year comparisons that need no ad-product / campaign / ad group / keyword / search-term / placement breakdown; query_advertising is the advertising CONSOLE for those breakdowns — Sponsored Products + Brands + Brands Video + Display as disjoint blocks, each at its own attribution window (SP 7-day on Seller Central and 14-day on Vendor Central, SB 14-day, SD 14-day click-attributed) and its own history floor (~60 days before the Ads connection at best). ⚠️ CAVEATS: the response may carry cogsNotice (units sold with no COGS — profit and margins overstated; cogsCoverage always comes with a COGS-based metric), marketplaceNotice (the totals add up several marketplaces, e.g. US + CA + MX on a North America account, while Amazon screens show one), adsHistoryNotice (part of the period predates the account's ads data) and subscribeAndSaveNotice (Subscribe & Save figures of a period not final yet, or partly without S&S data). Each notice, when present, MUST be relayed to the user before the figures it qualifies. 🔁 SUBSCRIBE & SAVE (Seller Central only): shippedSubscriptionUnits (S&S Units), totalSubscriptionsRevenue (S&S Sales), lostSubscriptionsRevenue (S&S Sales Lost to Stockouts) and missedSubscriptionUnits (S&S Units Missed to Stockouts: Nova's estimate, in units, of the subscription deliveries Amazon missed for lack of stock, from Amazon's report; a floor when a day cannot be priced) are flows summed over the days, final 7 days after the day. subscribeAndSaveDiscount (S&S Discount Funded) is the discount the seller funded on subscriber orders, read from the order lines rather than from Amazon's S&S report, on the SKU of each order line, so neither the report's delay, its S&S data coverage nor the per-ASIN rule below applies to it. It moves with the order lines like productPromotions (Customer promotions), of which it is a part, served with its sign (never add the two): its last days rise as subscriber orders ship, and an order line can still be revised for weeks. On a line that also carried a coupon it is an estimate, usually low. Read it next to S&S Sales and never subtract it from S&S Sales, which is neither gross nor net of it. activeSubscriptions is a LEVEL, known 4 days after the day: the subscriptions active at the END of the period (each account and marketplace on its last day with S&S data in the period, added up across them), never added up over days nor averaged; in a time series each bucket is the level at its own end. salesPenetration (S&S Sales divided by product sales, both summed over the days that have S&S data only) and subscriptionsStockoutRate (S&S Sales Lost to Stockouts divided by S&S Sales plus that loss, both summed over the period, a day Amazon has not served counting on neither side) are ratios of sums, final 7 days after the day: never average daily or per-product values, ask for the period and the grouping you need. A period that ends within a figure's delay is PARTIAL: its figure is served flagged as partial, with the day it becomes final (its last day plus the delay); a period with no final day yet has no value: its figure is null (never the 0 or the partial amount Amazon has published so far), and a ranking or a threshold on it is refused. A period that holds days Nova has no S&S data for (before the account's S&S history, a day missing or held out, a feed that stopped) is INCOMPLETE, with no day to become final. When either period of a comparison is partial or incomplete, the S&S figure keeps its value but its change (variance, variance_percentage) is null. Never present a partial or incomplete figure as complete, nor compare it with another period: a partial or incomplete sum is too low, never a drop. Amazon reports S&S per ASIN, and Nova puts each ASIN's S&S figures on ONE of its SKUs (the first in alphabetical order): a sku or tag row, or a skus or tags filter, therefore holds the whole ASIN's figures or none of them, so read S&S per childAsin or coarser. The answer says which periods are partial or incomplete, and why, in subscribeAndSaveNotice (relay it) and subscribeAndSaveCoverage (per period state and finalBy for the delay and complete; per account and marketplace its days without data). The state of the programme and of each product today is query_subscribe_and_save. 🧾 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. 🧮 BASIS: basis picks which P&L the figures are. Omitted or "order" (what this tool always served): the order-based P&L, every amount at the day the order was purchased, the last days brought up to the live orders. "cash": the cash-based P&L, every amount at the day Amazon POSTED it, RELEASED postings only (a DEFERRED posting is a reserve, not cash) — the reading that ties to the settlement reports; no live overlay, Seller Central accounts only, and refused (never answered on the other basis) where the cash P&L is not enabled. Pick "cash" when the user speaks of settlements, payouts, disbursements, what Amazon paid, or reconciling with the bank; keep the order basis for sales performance. A cash answer carries basis: "cash" and a basisNote to relay once. What separates the two readings of a month is query_pnl_bridge.