Seller Analytics Dataset Use Case Guide

This guide describes the specifics of the Seller Analytics dataset. For general information about the usage of Data Kiosk, refer to Data Kiosk API.

The seller analytics dataset in Data Kiosk has the following benefits:

• Cross-domain analytics: Structure custom queries to access metrics across multiple domains such as sales, traffic, promotions, account health, search, reviews, defects, and returns. You can do this in a single query to explore Selling Partner use cases and address business priorities. Additionally, this dataset allows you to aggregate data at date, ASIN, MSKU, brand, and other granularities in the same query. For example, you can view sales metrics per day, week, or month at ASIN granularity.
• Comprehensive metrics: More than 100 metrics across the sales, traffic, promotion, account health, search, reviews, defects, and returns domains.
• Multi-store queries: Retrieve data for multiple Amazon stores in a single call, provided all requested stores are in the same region.
• Period-over-period benchmarking: Request week-over-week, month-over-month, and year-over-year comparisons alongside the metric values themselves, without issuing a second query for the prior period.
• JSONL reports: All reports are returned in a scalable JSON Lines format.
• Secure data access: Request visibility is limited to requests submitted by a given application, ensuring security of Selling Partner data.

Access the schema

To access the seller analytics schema, download the schema: analytics_sellerAnalytics_2025_03_31.graphql. You can use any GraphQL tool to explore the schema and build queries. You cannot submit queries from these tools.

To submit the queries and retrieve your custom report, follow the steps in the Data Kiosk Use Case Guide.

The dataset exposes a single view, sellerAnalyticsView, on the analytics_sellerAnalytics_2025_03_31 domain. This one view spans all metric domains.

sellerAnalyticsView takes the following arguments:

The view is available to seller accounts only.

Metric access rights

Access to the seller analytics dataset is governed by the role assigned to your application. Two access levels apply:

• Sales and traffic access: Grants the sales, traffic, promotion, account health, search, reviews, defects, and returns metric groups, and the asin, productTitle, msku, brand, brandCode, parentAsin, fulfillmentChannel, productGroup, and marketplaceId group-by attributes.
• Sales and lending access: Grants the lending metric group, the sellerAttributes object, and the encryptedMerchantCustomerId group-by attribute, in addition to the fulfillmentChannel and marketplaceId group-by attributes.

Requesting a field your application is not authorized for returns an authorization error rather than a null value. If your application is authorized for a restricted set of Amazon stores, requesting a store outside that set returns Unauthorized marketplace access.

Metrics by domain

Refer to the schema for the definition of each metric.

sales

• averageSellingPrice
• orderedProductSales
• ordersShippedWithRevenue
• unitsOrdered
• unitsShipped
• orderGMS

The following B2B sales metrics are defined in the schema but are not yet available. See Metrics that are not yet available.

• averageSellingPriceB2B
• orderedProductSalesB2B
• unitsShippedB2B

traffic

• browserPageViews
• browserSessions
• conversationRatePct
• featureOfferGlanceViews
• featureOfferPct
• glanceViews
• mobileAppPageViews
• mobileAppSessions
• pageViews
• sessions

The following B2B traffic metric is defined in the schema but is not yet available:

• glanceViewsB2B

promotion

• promotionConversionRate
• promotionGlanceViewCnt
• promotionOrderedUnitsWithRevenue
• promotionOrderedPrice
• promotionDiscountPct
• promotionDiscountAmt
• promotionStartDate
• promotionEndDate
• promotionAsinStateType
• promotionType
• promotionStatus
• dealOurPrice
• dealId
• dealTitle

accountHealth

Order and package counts:

• accountHealthOrderCount
• accountHealthNegativeFeedbackOrderCount
• accountHealthAtozClaimOrderCount
• accountHealthChargebackClaimOrderCount
• accountHealthLateShipmentOrderCount
• accountHealthPreFulfillmentCancelOrderCount
• accountHealthValidTrackingDefectPackageCount
• accountHealthPackageCount
• accountHealthPackageUnits
• accountHealthOnTimeDeliveryDefectPackageUnits
• accountHealthOnTimeDeliveryDefectPackageCount
• accountHealthTotalOrderDefects

Rates and scores:

• accountHealthOrderDefectRate
• accountHealthNegativeFeedbackRate
• accountHealthAtozGuaranteeClaimRate
• accountHealthChargebackClaimRate
• accountHealthLateShipmentRate
• accountHealthPreFulfillmentCancelRate
• accountHealthValidTrackingRate
• accountHealthOnTimeDeliveryRate
• accountHealthRatingScore

Trailing 120-day product defect snapshot metrics. These metrics are not additive and are subject to additional date restrictions. See Snapshot metric behavior.

• regionResolvedDefectsUnitT120Days
• regionIncorrectLabelDefectRateT120Days
• regionLabelMissingDefectRateT120Days
• regionInaccurateProductDefectRateT120Days
• regionUnexpectedProductDefectRateT120Days
• regionOtherDefectsProductRelatedDefectRateT120Days
• regionDistinctCountDefectTypeT120Days

search

The search metric group has two parts:

• search.query returns metrics per search keyword. Each entry carries a queryKeyword and a priceAndCountMetrics object.
• search.catalog returns the same priceAndCountMetrics object aggregated across all keywords, plus clickRate, conversionRate, and trafficSales.

priceAndCountMetrics contains:

• impressionsWithPrice
• clicksWithPrice
• cartAddsWithPrice
• purchasesWithPrice
• sameDayMetrics, oneDayMetrics, twoDayMetrics, each carrying shippingImpression, shippingClick, shippingCartAdd, and shippingPurchase

reviews

Customer review counts and rates for each product in the selected time period.

• lowRatingReviewCount
• totalReviewCount
• criticalReviewRate

defects

Return-defect analytics derived from customer returns. The defects group has two parts:

• defects.topics returns metrics per return-defect topic. Each entry carries a returnDefectTopic and the following metrics:
  • returnDefectFrequency
  • returnDefectContribution
  • returnDefectRecommendations
• defects.totalDefectFrequency returns the total frequency of return defects across all topics for each product.

returns

Customer return volume and refund metrics for each product in the selected time period.

• returnedUnits
• totalRefundAmount
• returnedRate

lending

Available only to applications with sales and lending access.

• disbursements
• totalBalanceByStandardOrders
• refundsOrderCount
• feedbackOrderCount
• primaryProductCategory
• primaryProductCategoryNetGMS
• totalFbaInventoryValue

sellerAttributes

Available only to applications with sales and lending access. These are static account attributes and are not affected by the requested date range or granularity.

• sellerStoreURL
• isFBARegistered
• isBrandOwner
• sellerFraudStatus
• sellerTenure

Group-by attributes

Every query must select at least one attribute in groupByKey. The following attributes are available:

• asin
• productTitle
• msku
• brand
• brandCode
• parentAsin
• fulfillmentChannel
• productGroup
• marketplaceId
• encryptedMerchantCustomerId — requires sales and lending access

queryKeyword in the search domain also acts as a group-by attribute. It is selected inside search.query rather than in groupByKey, and selecting it automatically groups search results by keyword.

returnDefectTopic in the defects domain also acts as a group-by attribute. It is selected inside defects.topics rather than in groupByKey, and selecting it automatically groups defect results by topic.

Totals and grouped metrics

sellerAnalyticsView returns two parallel structures over the same metric type:

• totals: metric values aggregated across your entire catalog for the time period.
• metrics: an array of entries, each with a groupByKey and the metric values for that key.

The following are not supported in totals: the trailing 120-day product defect snapshot metrics listed under accountHealth, criticalReviewRate, returnedRate, and all fields in the defects group. Requesting them there returns The following fields are not supported in totals.

Metric domain-specific behavior

Some metric groups are not additive across time periods, or are not resolved from the same underlying data as the rest of the dataset. This section describes those behaviors.

Snapshot metric behavior

The trailing 120-day product defect metrics in the accountHealth group are snapshots rather than period sums. They represent a state at a point in time and cannot be added across periods.

When a request contains these metrics, additional date restrictions apply:

• Daily: The startDate and endDate must be the same date, and that date must be one for which snapshot data exists. If they are not, the error message identifies the valid dates.
• Weekly: Eight weeks. This time period includes the current week and the previous seven weeks.
• Monthly: 24 months. This time period includes the current month and the previous 23 months.

A query may mix snapshot metrics with ordinary period metrics. When it does, the two sets are resolved separately and merged into one response, so the snapshot restrictions above still apply to the request as a whole.

B2B metric behavior

The B2B metrics (averageSellingPriceB2B, orderedProductSalesB2B, unitsShippedB2B, glanceViewsB2B) are declared in the schema but are not yet served. Requesting one returns The following fields are not yet supported. See Metrics that are not yet available.

Promotion attribute behavior

The following fields in the promotion group describe the promotion itself rather than measuring performance:

• promotionStartDate
• promotionEndDate
• promotionAsinStateType
• promotionType
• promotionStatus
• dealId
• dealTitle

These are attributes of the promotion and are not additive across periods.

Search domain behavior

Search metrics are grouped by keyword through queryKeyword rather than through groupByKey. Because a keyword is not a catalog attribute, grouping by it affects which metrics can be returned alongside it. See Column compatibilities.

Defects snapshot behavior

The defects metrics are snapshots computed over a trailing six-month window, not period sums. They represent the state of each product's return defects as of the latest available snapshot and cannot be added across periods. Each product carries one return-defect topic per snapshot; a topic can change from one snapshot to the next as the trailing window moves.

Returns behavior

Returns are attributed to the day the returned unit was shipped, not the day it was returned. Return data is computed with a delay of about 45 days, so:

• returnedUnits and totalRefundAmount for the most recent ~45 days may be null or incomplete.
• returnedRate may appear artificially low for recent dates, because returned units lag while shipped units are current.

Catalog-only requests

Requests that select only group-by attributes and no metrics are not supported. Such a request returns Catalog requests (i.e. requests containing only GroupBy metrics) are not supported yet. Every query must select at least one metric alongside its groupByKey.

Date behavior

The query outputs automatically adjust the startDate and endDate based on the requested date granularity. Every request is checked to ensure that the requested date is valid. For example, startDate must be in the past, startDate must be before or equal to endDate, and startDate must be no more than two years ago.

Adjustments:

• Weekly: The startDate is rolled back to the preceding Sunday and the endDate is rolled back to the preceding Saturday, so that the range covers whole weeks. After adjustment the range must span at least seven days; a narrower range returns an error that identifies the most recent valid week.
• Monthly: The startDate is rolled back to the first day of its month. If the endDate is not already the last day of a month, it is rolled back to the last day of the preceding month, so that the range covers whole months.
• Daily: No adjustment is applied.
• Data availability: The endDate is additionally capped to the most recent date for which all requested metrics have data. If the startDate is later than that date, the request returns an error identifying the latest available date for the requested granularity.
• Partial data availability: There are situations where data is available for parts of a time period, but not for the entire time period. This scenario occurs when data is requested within one to two business days. In such cases, the response for periods that are unavailable contains null values.

Benchmarking behavior

Every numeric metric can carry a timeRangeBenchmarking object expressing the percentage change against a prior comparable period. Which comparisons are available depends on aggregateBy:

Requesting a benchmark that is not available for the selected granularity returns Unsupported TimeRangeBenchmarking requested for <granularity> granularity, along with the list of benchmarks that granularity does support. In particular, no benchmarking is available at DAY granularity.

If you do not select any timeRangeBenchmarking subfields, the object is null and no additional work is performed to compute it.

For rate metrics (criticalReviewRate, returnedRate, returnDefectContribution), the benchmark is the difference between the two periods' rates expressed in percentage points, rather than a percentage change.

Column compatibilities

Not every metric can be broken down by every group-by attribute. Compatibility is evaluated per request, against the attributes you selected in groupByKey.

Requesting an incompatible combination is not an error. When a query groups by an attribute and also requests metrics that are not available at that granularity, the request is resolved in parts and merged into a single response. Metrics that cannot be broken down by the requested attribute are returned as null for those rows, rather than being dropped or causing the query to fail.

Practically, this means you should read a null in a grouped row as "this metric is not available at this granularity" rather than as "this metric was zero". If you need to distinguish the two, request the metric in a second query that omits the attribute it is incompatible with.

The one case that does return an error is a set of metrics with no overlapping data availability at all. That returns The requested columns are not compatible together with the list of requested columns.

Rules for query construction

• All queries must have at least one group-by field.

• All queries must request at least one metric. Group-by attributes alone are not sufficient.

• All requested Amazon stores must be in the same region. For example, a single query cannot request data for the US and GB stores.

• Requested currency must be one of the supported ISO 4217 codes:

  • AED
  • AUD
  • BRL
  • CAD
  • CLP
  • CNY
  • COP
  • EGP
  • EUR
  • GBP
  • INR
  • JPY
  • MXN
  • NGN
  • PLN
  • SAR
  • SEK
  • SGD
  • TRY
  • USD
  • ZAR

  If currencyCode is omitted, amounts are returned in USD.

• aggregateBy must be DAY, WEEK, or MONTH.

Sample queries

Seller sales report

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-01"
      endDate: "2025-03-31"
      aggregateBy: WEEK
      currencyCode: "USD"
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      totals {
        sales {
          orderedProductSales {
            amount {
              amount
              currencyCode
            }
          }
          unitsOrdered {
            value
          }
        }
      }
      metrics {
        groupByKey {
          asin
          brand
        }
        metrics {
          sales {
            averageSellingPrice {
              amount {
                amount
                currencyCode
              }
            }
            orderedProductSales {
              amount {
                amount
                currencyCode
              }
            }
            ordersShippedWithRevenue {
              unitsWithValue {
                units
                value {
                  amount
                  currencyCode
                }
              }
            }
            unitsOrdered {
              value
            }
            unitsShipped {
              value
            }
            orderGMS {
              amount {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

Seller traffic report

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-01"
      endDate: "2025-03-31"
      aggregateBy: WEEK
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
        }
        metrics {
          traffic {
            glanceViews {
              value
            }
            pageViews {
              value
            }
            sessions {
              value
            }
            browserPageViews {
              value
            }
            mobileAppPageViews {
              value
            }
            conversationRatePct {
              value
            }
            featureOfferPct {
              value
            }
          }
        }
      }
    }
  }
}

Cross-domain report with benchmarking

Benchmarking is available at WEEK and MONTH granularity only.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-01-01"
      endDate: "2025-03-31"
      aggregateBy: MONTH
      currencyCode: "USD"
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
          parentAsin
        }
        metrics {
          sales {
            orderedProductSales {
              amount {
                amount
                currencyCode
              }
              timeRangeBenchmarking {
                monthOverMonth
                yearOverYear
              }
            }
          }
          traffic {
            glanceViews {
              value
              timeRangeBenchmarking {
                monthOverMonth
                yearOverYear
              }
            }
          }
        }
      }
    }
  }
}

Seller promotion report

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-01"
      endDate: "2025-03-31"
      aggregateBy: WEEK
      currencyCode: "USD"
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
        }
        metrics {
          promotion {
            promotionType
            promotionStatus
            promotionStartDate
            promotionEndDate
            promotionGlanceViewCnt {
              value
            }
            promotionConversionRate {
              value
            }
            promotionDiscountPct {
              value
            }
            promotionOrderedUnitsWithRevenue {
              unitsWithValue {
                units
                value {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
    }
  }
}

Seller account health report

The trailing 120-day snapshot metrics are omitted here so that the query is not subject to the snapshot date restrictions.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-01"
      endDate: "2025-03-31"
      aggregateBy: MONTH
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      totals {
        accountHealth {
          accountHealthOrderCount {
            value
          }
          accountHealthOrderDefectRate {
            value
          }
          accountHealthLateShipmentRate {
            value
          }
          accountHealthValidTrackingRate {
            value
          }
          accountHealthOnTimeDeliveryRate {
            value
          }
          accountHealthRatingScore {
            value
          }
        }
      }
    }
  }
}

Account health snapshot report

Snapshot metrics at DAY granularity require the same startDate and endDate, and that date must be one for which snapshot data is available.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-31"
      endDate: "2025-03-31"
      aggregateBy: DAY
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
        }
        metrics {
          accountHealth {
            regionResolvedDefectsUnitT120Days {
              value
            }
            regionIncorrectLabelDefectRateT120Days {
              value
            }
            regionLabelMissingDefectRateT120Days {
              value
            }
            regionInaccurateProductDefectRateT120Days {
              value
            }
            regionDistinctCountDefectTypeT120Days {
              value
            }
          }
        }
      }
    }
  }
}

Seller search report

Selecting queryKeyword groups the search results by keyword.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-01"
      endDate: "2025-03-31"
      aggregateBy: WEEK
      currencyCode: "USD"
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
        }
        metrics {
          search {
            query {
              queryKeyword
              priceAndCountMetrics {
                impressionsWithPrice {
                  unitsWithValue {
                    units
                    value {
                      amount
                      currencyCode
                    }
                  }
                }
                clicksWithPrice {
                  unitsWithValue {
                    units
                    value {
                      amount
                      currencyCode
                    }
                  }
                }
                purchasesWithPrice {
                  unitsWithValue {
                    units
                    value {
                      amount
                      currencyCode
                    }
                  }
                }
                twoDayMetrics {
                  shippingImpression {
                    value
                  }
                  shippingClick {
                    value
                  }
                  shippingPurchase {
                    value
                  }
                }
              }
            }
            catalog {
              clickRate {
                value
              }
              conversionRate {
                value
              }
              trafficSales {
                amount {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
    }
  }
}

Seller reviews and returns report

returnedRate and criticalReviewRate are not supported in totals, so they are requested only in the grouped metrics.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2026-03-01"
      endDate: "2026-03-31"
      aggregateBy: MONTH
      currencyCode: "USD"
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      totals {
        reviews {
          lowRatingReviewCount {
            value
          }
          totalReviewCount {
            value
          }
        }
        returns {
          returnedUnits {
            value
          }
          totalRefundAmount {
            amount {
              amount
              currencyCode
            }
          }
        }
      }
      metrics {
        groupByKey {
          asin
        }
        metrics {
          reviews {
            lowRatingReviewCount {
              value
            }
            totalReviewCount {
              value
            }
            criticalReviewRate {
              value
              timeRangeBenchmarking {
                monthOverMonth
              }
            }
          }
          returns {
            returnedUnits {
              value
              timeRangeBenchmarking {
                monthOverMonth
              }
            }
            totalRefundAmount {
              amount {
                amount
                currencyCode
              }
            }
            returnedRate {
              value
            }
          }
        }
      }
    }
  }
}

Return defect topics report

Selecting returnDefectTopic groups the defect results by topic.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2026-03-01"
      endDate: "2026-03-31"
      aggregateBy: MONTH
      marketplaceId: ["ATVPDKIKX0DER"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
        }
        metrics {
          defects {
            topics {
              returnDefectTopic
              returnDefectFrequency {
                value
              }
              returnDefectContribution {
                value
              }
              returnDefectRecommendations
            }
            totalDefectFrequency {
              value
            }
          }
        }
      }
    }
  }
}

Multi-store report

All requested stores must be in the same region.

query MyQuery {
  analytics_sellerAnalytics_2025_03_31 {
    sellerAnalyticsView(
      startDate: "2025-03-01"
      endDate: "2025-03-31"
      aggregateBy: WEEK
      currencyCode: "USD"
      marketplaceId: ["ATVPDKIKX0DER", "A2EUQ1WTGCTBG2"]
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
          marketplaceId
        }
        metrics {
          sales {
            unitsOrdered {
              value
            }
            orderedProductSales {
              amount {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

Error messages

Metrics that are not yet available

The following metrics appear in the schema but are not yet served. Requesting them returns The following fields are not yet supported.

• averageSellingPriceB2B
• orderedProductSalesB2B
• unitsShippedB2B
• glanceViewsB2B

FAQ

When is data ready?

All metrics in the seller analytics dataset are ready after 34 hours. Data for a given day is generally available at 10 AM local time two days later. For example, data for January 1st is available at 10 AM local time on January 3rd. In the event that data is delayed and unavailable, the response is null for the specific date or dates for which data is unavailable.

Why is a metric null in a grouped row when the same metric returns a value elsewhere?

The metric is not available at the granularity you grouped by. Requesting metrics that are unavailable at a requested granularity does not fail the query; the unavailable metrics are returned as null for those rows. Re-request the metric without the attribute it is incompatible with to get its value. See Column compatibilities.

Can I request a benchmark at daily granularity?

No. Benchmarking is available at WEEK and MONTH granularity only.

Can I query multiple Amazon stores in one request?

Yes, provided all requested stores are in the same region. A request spanning regions returns All requested marketplaces must be in the same region.

Can I retrieve catalog attributes without requesting any metrics?

No. Requests that select only group-by attributes are not supported. Include at least one metric alongside your groupByKey.

Why does returnDefectTopic show only one topic per product?

Each product carries one return-defect topic per snapshot, reflecting the trailing six-month window. The topic can change between snapshots as the window moves.