HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Vendor Analytics Dataset Use Case Guide

How to use the Vendor Analytics dataset with Data Kiosk.

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

The vendor 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, and inventory. 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, brand manufacturing, and other granularities in the same query. For example, you view sales metrics per day, week, or month at ASIN granularity.
  • Comprehensive metrics: More than 100 metrics across sales, traffic, inventory, and forecast domains.
  • Efficient API calls: Retrieve only the data you need with minimal API calls. Additionally, you can fetch data from multiple marketplaces that you operate in with a single API call.
  • JSONL reports: All reports are vended 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 vendor analytics schema, download the schema: analytics_vendorAnalytics_2024_09_30.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

Metric access rights

The analytics_vendorAnalytics_2024_09_30 dataset has a sourcingView and manufacturingView. You access the relevant view and its associated metrics based on the role assigned to the vendor (SOURCING or MANUFACTURING).

Manufacturing refers to any ASINs manufactured by the vendor, whereas Sourcing refers only to ASINs sourced directly from the vendor to Amazon (meaning the vendor is a distributor).

  • sourcingView: Shows only data of ASINs sourced directly from the vendor. The metrics available in the sourcing view are listed in Metrics in sourcing view. Certain metrics such as Glance Views are not available in sourcingView, and that sourcingView is the same as distributor view.
  • manufacturingView: Shows data for all ASINs manufactured by the vendor (regardless of who sourced the products to Amazon). If a vendor (Vendor Group) does not manufacture any ASINs, then the query for accessing manufacturing view for the vendor returns Error: VendorGroup does not have relevant rights to perform this operation.

The vendor dataset allows for flexibility and cross-domain joins.

Metrics in sourcing view

The following set of metrics are available in the Sourcing View and vary depending on the category and domain. Refer to the schema for the definition of each metric.

  • ProductAvailability
    • sellableOnHandInventory
    • unsellableOnHandInventory
    • aged90DaysSellableInventory
    • unhealthyInventory
    • sellThroughRate
    • ultraFastTrack
  • Orders
    • orderedUnitsWithRevenue
    • unfilledOrderedUnits
  • ShippedOrders
    • shippedUnitsWithRevenue
  • CustomerSatisfaction
    • customerReturns
  • Traffic
    • glanceViews
  • Sourcing
    • vendorConfirmationRate
    • overallVendorLeadTime
    • netReceived
    • receivedFillRate
    • procurableProductOOS
    • openPurchaseOrderQuantity
  • Forecasting
    • mean
    • p70
    • p80
    • p90
  • Costs
    • netPPM
    • salesDiscount

Metric domains specific behavior

Some metric domains are not additive across time periods (for example, inventory metrics for a week cannot be added for each day). This section provides descriptions of behaviors of these metric groups.

Forecasting domain behavior

The forecasting domain contains forecasts that Amazon makes from Week zero to Week 47. Week zero is relative to the date on which the forecast was generated by Amazon.

This is a domain that is not additive across time periods, which means:

  • Any date range provided in the query are not applicable for these metrics.
  • The forecasts are refreshed on a weekly basis with new values refreshed for Week zero to Week 47 relative to forecast creation date.

Inventory domain behavior

Inventory metrics are a snapshot of the number of units available to be sold at the end of a period of time. These metrics are not additive and are only available for predefined time periods that are relevant to business decisions.

The currently supported time periods are:

  • Daily: Only supported for the current common date. If you provide an invalid date, then the error message contains the correct date to use.
  • 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.

Catalog attribute behavior

Catalog attributes (for example, ASINs and product titles) are always current and latest. There is no historical view of catalog data. Information about an ASIN is always based on the latest definition and there is no concept of “as of x date” for catalog reports.

Start- and end-dates provided in the query are not applicable to catalog attributes. When a query contains only catalog attributes and no metrics, the start- and end-data values provided are immaterial and the latest value for the catalog attribute is returned.

📘

Note

shipToCountryCode, shipToCity, and shipToStateOrProvince are not available in the Catalog report.

Date behavior

The query outputs are currently configured to automatically adjust the startDate and endDate based on the requested view and relevant date granularity selected. Certain checks are performed on every request to ensure that the requested date is valid. For example, startDate must be in the future and endDate must be before startDate.

Adjustments:

  • The startDate for all reports weekly/monthly are adjusted to the beginning of a given time period. This means that weekly time periods always begin on Sunday, and monthly time periods always begin on the first day of the month.
  • The endDate for all reports are adjusted to the end of a complete and valid time period. This means that the endData cannot be in the future.
  • Partial data availability: There are situations where data is available for parts of a time period, but not available for the entire time period. This scenario occurs when data is requested within one to two business days. In such cases, the response for days that are unavailable contains a null value.

Rules for query construction

  • All queries should have at least one group-by field.
  • When the data requested exceeds 1.5 GB, the response is truncated, and there might be missing rows or information.

Sample queries

Vendor sales report

SourcingView:

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    sourcingView(
      startDate: "2023-12-01"
      endDate: "2024-02-28"
      aggregateBy: WEEK
      currencyCode: "USD"
    ) {
      startDate
      endDate
      marketplaceId
      totals {
        shippedOrders {
          shippedUnitsWithRevenue {
            units
            value {
              amount
              currencyCode
            }
          }
        }
      }
      metrics {
        groupByKey {
          asin
          brandCode
        }
        metrics {
          shippedOrders {
            shippedUnitsWithRevenue {
              units
              value {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

ManufacturingView:

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    manufacturingView(
      startDate: "2023-12-01"
      endDate: "2024-02-28"
      aggregateBy: WEEK
      currencyCode: "USD"
    ) {
      startDate
      endDate
      marketplaceId
      totals {
        shippedOrders {
          shippedUnitsWithRevenue {
            units
            value {
              amount
              currencyCode
            }
          }
        }
        orders {
          unfilledOrderedUnits
          orderedUnitsWithRevenue {
            units
            value {
              amount
              currencyCode
            }
          }
        }
        costs {
          netPPM
        }
      }
      metrics {
        groupByKey {
          asin
          brandCode
        }
        metrics {
          shippedOrders {
            shippedUnitsWithRevenue {
              units
              value {
                amount
                currencyCode
              }
            }
          }
          orders {
            unfilledOrderedUnits
            orderedUnitsWithRevenue {
              units
              value {
                amount
                currencyCode
              }
            }
          }
          costs {
            netPPM
          }
        }
      }
    }
  }
}

Vendor traffic report

The traffic report is only available for manufacturingView.

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    manufacturingView(
      startDate: "2023-12-01"
      endDate: "2024-02-28"
      aggregateBy: WEEK
    )
    startDate
    endDate
    marketplaceId
    totals {
      traffic {
        glanceViews
      }
    }
    metrics {
      groupByKey {
        asin
        brandCode
      }
      metrics {
        traffic {
          glanceViews
        }
      }
    }
  }
}

Vendor forecasting report

The forecasting report is only available for manufacturingView.

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    manufacturingView(
      startDate: "2023-12-01"
      endDate: "2024-02-28"
      aggregateBy: WEEK
    )
    startDate
    endDate
    marketplaceId
    metrics {
      groupByKey {
        asin
        brandCode
      }
      metrics {
        forecasting {
          startDate
          endDate
          weekNumber
          demand {
            mean
            p70
            p80
            p90
          }
        }
      }
    }
  }
}

Vendor inventory report

The inventory report is available for both sourcingView and manufacturingView. Inventory reports are not additive.

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    sourcingView(
      startDate: "2023-12-01"
      endDate: "2024-02-28"
      aggregateBy: WEEK
      currencyCode: "USD"
    ) {
      startDate
      endDate
      marketplaceId
      metrics {
        groupByKey {
          asin
          brandCode
        }
        metrics {
          productAvailability {
            sellableOnHandInventory {
              units
              value {
                amount
                currencyCode
              }
            }
            unsellableOnHandInventory {
              units
              value {
                amount
                currencyCode
              }
            }
            aged90DaysSellableInventory {
              units
              value {
                amount
                currencyCode
              }
            }
            unhealthyInventory {
              units
              value {
                amount
                currencyCode
              }
            }
            sellThroughRate
            ultraFastTrack
          }
        }
      }
    }
  }
}

Catalog report

sourcingView:

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    sourcingView(
      startDate: "2024-05-25"
      endDate: "2024-05-25"
      aggregateBy: DAY
      currencyCode: "USD"
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
          productGroup
          productTitle
        }
      }
    }
  }
}

manufacturingView:

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    manufacturingView(
      startDate: "2024-05-01"
      endDate: "2024-05-29"
      aggregateBy: DAY
      currencyCode: "USD"
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
          brandCode
          brand
          parentAsin
        }
      }
    }
  }
}

Geo Sales report

sourcingView:

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    sourcingView(
      aggregateBy: WEEK
      endDate: "2024-05-31"
      startDate: "2024-05-01"
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
          shipToCountryCode
          shipToCity
          shipToStateOrProvince
        }
        metrics {
          shippedOrders {
            shippedUnitsWithRevenue {
              value {
                amount
                currencyCode
              }
              units
            }
          }
        }
      }
    }
  }
}

manufacturingView:

query MyQuery {
  analytics_vendorAnalytics_2024_09_30 {
    manufacturingView(
      aggregateBy: WEEK
      endDate: "2024-05-31"
      startDate: "2024-05-01"
    ) {
      startDate
      endDate
      metrics {
        groupByKey {
          asin
          shipToCountryCode
          shipToCity
          shipToStateOrProvince
        }
        metrics {
          shippedOrders {
            shippedUnitsWithRevenue {
              value {
                amount
                currencyCode
              }
              units
            }
          }
        }
      }
      totals {
        shippedOrders {
          shippedUnitsWithRevenue {
            units
            value {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
}

Error messages

ErrorDescription
The requested columns are not compatible <requested columns> and no common date could be found.Indicates that the columns provided in the request are not compatible and therefore cannot be queried together.
Start date should be before or equal to the end date.The requested startDate cannot be after the requested endDate.
End date cannot be in the futureThe requested endDate cannot be a future date.
Start date must be no more than two years ago.The requested startDate is more than two years ago, which is not a valid input.
Need at least one groupable column in request.At least one column must be added to the groupByKey in the request.
Selected Currency <currency> not supported.The currency provided in the request is not supported.
Selected Granularity <granularity> not supported.The aggregateBy field must be either DAY, WEEK, or MONTH.
VendorGroup does not have relevant rights to perform this operation.The vendor requested manufacturingView without having any ASINs that they manufacture.
Weekly Inventory data is only available for 8 weeks, including the current week.The request is for a weekly granularity, contains Inventory metrics, and the provided start date is more than eight weeks ago (including the current week).
Monthly Inventory metrics are only available for 24 months, including the current month.The request is for a monthly granularity, contains Inventory metrics, and the provided start date is more than 24 months ago (including the current month).
Daily Inventory metrics are only supported for the current common date of <yyyy-mm-dd>The request is for a daily granularity, contains Inventory metrics, and the provided start date and end date do not match or are not for the most current date. The most recent date is provided in the error message.
Requested marketplace is not supported.The marketplaceId provided in the request is not supported.
getLeadingDate: Unrecoverable error retrieving leading date for viewUnable to determine a date to serve the requested metrics for. This error can be the result of an availability issue.

FAQ

When is data ready?

All metrics in the vendor analytics dataset are ready after 34 hours. Data for a given day is 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 there a 0 for some dates?

When there are no sales on a given day, the response for that day contains 0 or similar placeholder data.