selling-partner-seller-analytics

Overview

Retrieves a seller's business-performance metrics (Fulfillment by Amazon (FBA) inventory health, storefront traffic, and sales) through the Selling Partner API (SP-API) analytics operations and reports them in plain language. It is read-only: it discovers what metrics exist, queries their values, and explains them, and never changes a price, listing, or shipment. Its one hard rule is discover before you query: the agent must not guess metric names, because guessing returns the wrong data. It is the reporting member of the SP-API seller family; for acting on a stockout risk it surfaces, it points the seller to selling-partner-stockout-prevention.

Workflow

<Definition - Measure vs Dimension> The two kinds of column the metadata returns. A measure is a numeric value to report (isGroupable false); it goes in the request's metrics array. A dimension is a column to group or filter by (isGroupable true), for example ASIN or MARKETPLACE_ID; it goes in groupBy or the filter. Reading isGroupable correctly is how you decide where a column belongs in the request. </Definition - Measure vs Dimension>

<Definition - Grain> The level a metric's data exists at (for example marketplace-level, ASIN-level). A single metric can be grouped by any column it is groupable on. To combine several metrics in one query they must share a grain: the metadata's domains availability lists the commonGrains shared across metrics, and a combined query may group only by a column in that shared set. Metrics at different grains must be queried separately. </Definition - Grain>

<Definition - Marketplace Filter> A required condition inside the query's groupableColumnFilter that carries a MARKETPLACE_ID leaf using EQUALS (one marketplace) or IN (several) with an actual value. It is required on every data query even though the marketplace is also passed at the top level. A predicate operator (IS_NULL, IS_NOT_NULL, LIKE) or a filter on another column alone (for example ASIN only) does not satisfy it, and such a request is rejected. To also filter by another dimension, wrap both in an AND. Full request shapes are in references/request-reference.md. </Definition - Marketplace Filter>

<Definition - Active Context> The one merchant account (entityId, the Merchant Token / MCID) plus one marketplace pinned for the session after the connector resolves the seller. Every analytics call carries this pair explicitly (the gateway does not auto-populate entityId). It exists only for the session and is never persisted (Rule 8). </Definition - Active Context>

<Workflow - Report Seller Analytics description="Answer a seller's inventory, traffic, or sales question read-only: establish context, discover the right metric, build a correct query, handle pagination and empty results, and explain the numbers in plain language." tools=[] triggers=["how are my sales", "how are my sessions", "how is my traffic", "am I at risk of a stockout", "how much inventory do I have", "what is my days of supply", "page views by ASIN", "when should I restock", "seller analytics", "business report"]

1. [Agent] Confirm the built-in Amazon Selling Partner connector is connected before any work, per the README pre-requisites. The analytics operations run through it. Validate: The connector is connected and its analytics operations are reachable. If fails: Tell the seller the Amazon Selling Partner connector must be connected and authenticated (from onboarding or Settings > Capabilities), and stop rather than simulating a result.

2. [Agent] Establish account context (pre-resolved). The connector resolves the seller's merchant account(s) and marketplace(s) at the start of the session. Pin exactly one entityId and one marketplace before any query; if several are in scope, ask which. Keep this context in the session only (Rule 8), and pass entityId explicitly on every call (Gotchas). Validate: Exactly one entityId and one marketplace are pinned. If fails: If no context is available, tell the seller the connector should resolve it on connect and ask them to confirm the account and marketplace; do not guess an identifier. If more than one is in scope and the seller has not chosen, ask rather than defaulting to the first.

3. [Decide] Is the seller's request in scope (inventory health, traffic, or sales reporting)?

   • In scope: continue to step 4.
   • A change to price, listing, or a shipment: decline the change (Rule 1), offer the relevant read-only numbers, and route to the right skill (selling-partner-stockout-prevention, the listing skills, or selling-partner-fba-inbound-management).
   • Tax or financial-settlement reporting, or listing copywriting: say this skill does not cover it and stop (Rule 11).

4. [Agent] Discover the right metric (never guess). Call the metric-metadata operation for the marketplace and read the response to find the metric ID that matches the seller's intent, confirming against each metric's business definition. Use the intent-to-metric map in references/metrics-catalog.md as a shortcut, but treat metadata as the source of truth. Note which columns are measures (isGroupable false) and which are dimensions (isGroupable true) per <Definition - Measure vs Dimension>. Validate: A metric ID present in the metadata is selected for the seller's intent. If fails: If the mapped metric is not in the metadata, pick the closest available one and say which you used; if nothing fits, tell the seller the metric is not available for this marketplace (Rule 5).

5. [Decide] Does the request need more than one metric?

   • One metric: continue to step 6.
   • Several metrics: check the metadata's domains availability and combine in one call only if they share a grain, grouping only by a column in the shared commonGrains (Rule 4, <Definition - Grain>). Otherwise split into separate calls. Validate: The planned call(s) group only by a column valid for all metrics in that call. If fails: Split the metrics into separate calls by grain and continue.

6. [Agent] Build and run the query. Call the metric-data operation with metrics as objects, a required dateGranularity, and a required groupableColumnFilter carrying a MARKETPLACE_ID condition (EQUALS or IN with a real value); add groupBy (for example ASIN) for a per-product breakdown, and combine a second dimension with MARKETPLACE_ID via AND. If the seller gave no dates, default to a recent window ending at least two days ago (Rule 10, Gotchas). Follow references/request-reference.md. Validate: The request is well-formed (metrics as objects, dateGranularity present, valued MARKETPLACE_ID filter present) and returns a result. If fails: If the request is rejected, correct the specific malformed field (most often a missing or predicate-only marketplace filter, missing dateGranularity, or string metrics) and retry.

7. [Decide] Are results paginated or empty?

   • Paginated (a nextToken is present): pass it back as paginationToken to fetch more, until complete or enough for the answer.
   • Empty: adjust the query at most once (widen the date range or drop groupBy for an aggregated total), say what you changed, and if still empty report there is no data for that range and ask the seller how to proceed (Gotchas).
   • Complete: continue to step 8. Validate: All needed pages are retrieved, or an empty result is handled with a single adjustment. If fails: Report what was retrieved and what remains unknown rather than looping.

8. [Agent] Explain, do not dump. Report the numbers in plain language tied to the seller's question, apply any stated analysis rule (for example days of supply under 14 is at risk of stockout), and state the date window used and the roughly two-day data delay when recency matters. If a stockout risk surfaces and the seller may want to act, note that acting on it is selling-partner-stockout-prevention's job. Never fabricate a value or a trend the data does not show (Rule 5), and include the informational-not-advice note (Rule 11). Validate: A plain-language answer tied to the question is produced, with the window and delay stated where relevant. If fails: If any value is missing, say so and offer the closest available metric rather than inventing one.

</Workflow - Report Seller Analytics>

Reference files:

• references/metrics-catalog.md: the intent-to-metric shortcut map, the three analytics domains, and the key metrics per domain, with the reminder that live metadata is the source of truth for availability.
• references/request-reference.md: exact request and response shapes for the metadata and data operations, the mandatory marketplace filter, multi-metric and ASIN filtering, pagination, and the known gotchas.