Vendor Retail Analytics Reports Migration Guide

AmazonSPAPI

# Overview

This document explains changes to the vendor retail analytics reports and describes how to migrate the following reports:

  • GET_VENDOR_DEMAND_FORECAST_REPORT (replaced by GET_VENDOR_FORECASTING_REPORT)
  • GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT (replaced by GET_VENDOR_INVENTORY_REPORT)
  • GET_VENDOR_SALES_DIAGNOSTIC_REPORT (replaced by GET_VENDOR_SALES_REPORT and GET_VENDOR_TRAFFIC_REPORT)

Important: The GET_VENDOR_DEMAND_FORECAST_REPORT, GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT, and GET_VENDOR_SALES_DIAGNOSTIC_REPORT report types will be deprecated on June 27, 2022. For more information, refer to the Mapping Report Types table below.

# What are the vendor retail analytics report types?

The vendor retail analytics report types are a collection of reports that share timeseries data for a vendor’s business, including historical sales, traffic, inventory, and forecast metrics.

# New reports and features

New report types launched in March 2022:

  • GET_VENDOR_SALES_REPORT
  • GET_VENDOR_TRAFFIC_REPORT
  • GET_VENDOR_FORECASTING_REPORT
  • GET_VENDOR_INVENTORY_REPORT

The new report types include the following changes to improve the developer experience:

  • Sourcing data for reports from the same source used by Amazon retail category teams
  • Allowing integrators to specify different time range aggregations in their createReport request
  • Flattening the overall JSON report structure to simplify parsing

# Migration workflow

Use the following steps to migrate the GET_VENDOR_DEMAND_FORECAST_REPORT, GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT, and GET_VENDOR_SALES_DIAGNOSTIC_REPORT report types.

# Step 1. Generate and download the new reports

  1. Submit a createReport request for each of the four new reports (GET_VENDOR_SALES_REPORT, GET_VENDOR_TRAFFIC_REPORT, GET_VENDOR_FORECASTING_REPORT, and GET_VENDOR_INVENTORY_REPORT).
  2. Use the getReport and getReportDocument API operations to download the reports.
  3. Review the structure and content of the reports.

# Step 2. Modify your JSON parser to recognize the new report version and JSON structure

  1. For each report type, review the JSON structure of the report.

Note: The new reports are "flatter", which simplifies parsing.

  1. For each report type, take note of the different data elements in the report.

# Step 3. Switch your production pipelines to source data from the new report type.

  1. Modify your createReport request to align with the new report version parameters.

Note: Most new reports require the reportPeriod parameter, however, this parameter did not exist in GET_VENDOR_DEMAND_FORECAST_REPORT, GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT, and GET_VENDOR_SALES_DIAGNOSTIC_REPORT.

  1. Update your createReport request to use the new reportType value (for example, GET_VENDOR_SALES_REPORT).

  2. Test your pipeline.

# Step 4. (Optional) Backfill historical data

The new reports source data from a different data source than GET_VENDOR_DEMAND_FORECAST_REPORT, GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT, and GET_VENDOR_SALES_DIAGNOSTIC_REPORT. Amazon retail category teams also use this new source. Because of this source change, you may want to backfill historical data to ensure that you are not blending data from multiple sources.

# Mapping Report Types

Old New
Name Report Type Value Deprecation Date Name Report Type Value Notes
Sales Diagnostic Report GET_VENDOR_SALES_DIAGNOSTIC_REPORT June 27, 2022 Sales Report and Traffic Report GET_VENDOR_SALES_REPORT and GET_VENDOR_SALES_TRAFFIC_REPORT The new reports mimic the dashboards that will launch in Vendor Central later in 2022. Sales and traffic metrics are split out into different dashboards and therefore split out into different reports.
Inventory Health & Planning Report GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT June 27, 2022 Inventory Report GET_VENDOR_INVENTORY_REPORT
Demand Forecast Report GET_VENDOR_DEMAND_FORECAST_REPORT June 27, 2022 Forecasting Report GET_VENDOR_FORECASTING_REPORT
Net Pure Product Margin Report GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT Will not be deprecated This report launched using the new data source. Developers do not need to migrate off of this report.

##Mapping Data Elements

OldNew
Report Type ValueData ElementReportData Element(s)Notes
GET_VENDOR_SALES_DIAGNOSTIC_REPORTpreOrderedReveuen/an/aDeprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORTpreOrderedUnitsn/an/aDeprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORTorderedRevenueGET_VENDOR_SALES_REPORTorderedRevenue
GET_VENDOR_SALES_DIAGNOSTIC_REPORTorderedUnitsGET_VENDOR_SALES_REPORTorderedUnits
GET_VENDOR_SALES_DIAGNOSTIC_REPORTshippedRevenueGET_VENDOR_SALES_REPORTshippedRevenue
GET_VENDOR_SALES_DIAGNOSTIC_REPORTshippedUnitsGET_VENDOR_SALES_REPORTshippedUnits
GET_VENDOR_SALES_DIAGNOSTIC_REPORTshippedCogsGET_VENDOR_SALES_REPORTshippedCogs
GET_VENDOR_SALES_DIAGNOSTIC_REPORTglanceViewsGET_VENDOR_TRAFFIC_REPORTglanceViews
GET_VENDOR_SALES_DIAGNOSTIC_REPORTconversionRaten/an/aDeprecated but can be calculated: orderedUnits / glanceViews
GET_VENDOR_SALES_DIAGNOSTIC_REPORTlostBuyBoxn/an/aDeprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORTcustomerReturnsn/an/aDeprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORTfreeReplacementsn/an/aDeprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORTorderedSubcategorySalesRankn/an/aDeprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORTshippedSubcategorySalesRankn/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTnetReceivedAmountGET_VENDOR_INVENTORY_REPORTnetReceivedAmount
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTnetReceivedUnitsGET_VENDOR_INVENTORY_REPORTnetReceivedUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTopenPurchaseOrderQuantityGET_VENDOR_INVENTORY_REPORTopenPurchaseOrderQuantity
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTsellThroughRateGET_VENDOR_INVENTORY_REPORTsellThroughRate
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTsellableOnHandInventoryGET_VENDOR_INVENTORY_REPORTsellableOnHandInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTsellableOnHandAmountTrailing30DayAveragen/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTsellableOnHandUnitsGET_VENDOR_INVENTORY_REPORTsellableOnHandUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunsellableOnHandInventoryGET_VENDOR_INVENTORY_REPORTunsellableOnHandInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunsellableOnHandAmountTrailing30DayAveragen/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunsellableOnHandUnitsGET_VENDOR_INVENTORY_REPORTunsellableOnHandUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTaged90PlusDaysSellableInventoryGET_VENDOR_INVENTORY_REPORTaged90PlusDaysSellableInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTaged90PlusDaysSellableAmountTrailing30DayAveragen/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTaged90PlusDaysSellableUnitsGET_VENDOR_INVENTORY_REPORTaged90PlusDaysSellableUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunhealthyInventoryGET_VENDOR_INVENTORY_REPORTunhealthyInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunhealthyUnitsTrailing30DayAveragen/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTavailableUnitsn/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunhealthyUnitsunhealthyUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTunfilledCustomerOrderedUnitsunfilledCustomerOrderedUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTweeksOnHandn/an/aDeprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORTreceiveFillRaten/an/aDeprecated. See vendorConfirmationRate
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORToverallVendorLeadTimeoverallVendorLeadTime
GET_VENDOR_DEMAND_FORECAST_REPORTrelativeWeekGET_VENDOR_FORECASTING_REPORTstartDate and endDateUse startDate and endDate to calculate the week relative to the forecastGenerationDate
GET_VENDOR_DEMAND_FORECAST_REPORTdemandForecastType and demandUnitsGET_VENDOR_FORECASTING_REPORT

meanForecastUnits

p70ForecastUnits

p80ForecastUnits

p90ForecastUnits

# Example Inventory Report (old)

GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT

{
    "reportSummary": {
        "reportingDateRange": {
            "reportingDateFrom": "2021-08-01",
            "reportingDateTo": "2021-08-01"
        },
        "distributorView": "MANUFACTURER",
        "currencyCode": "USD"
    },
    "reportDetails": [
        {
            "sellingProgramName": "AMAZON_RETAIL",
            "inventoryHealthMetricsByProgram": [{
                    "asin": "B123456789",
                    "inventoryHealthMetricsByAsin": [{
                            "reportingDate": "2021-08-01",
                            "inventoryHealthMetricsByDate": {
                                "netReceivedAmount": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "netReceivedUnits": 0,
                                "openPurchaseOrderQuantity": 0,
                                "sellThroughRate": 0.0000,
                                "sellableOnHandInventory": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "sellableOnHandAmountTrailing30DayAverage": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "sellableOnHandUnits": 0,
                                "unsellableOnHandInventory": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "unsellableOnHandAmountTrailing30DayAverage": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "unsellableOnHandUnits": 0,
                                "aged90PlusDaysSellableInventory": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "aged90PlusDaysSellableAmountTrailing30DayAverage": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "aged90PlusDaysSellableUnits": 0,
                                "unhealthyInventory": {
                                    "amount": 0.00,
                                    "currencyCode": "USD"
                                },
                                "unhealthyUnitsTrailing30DayAverage": 0.00,
                                "unhealthyUnits": 0,
                                "unfilledCustomerOrderedUnits": 0,
                                "availableUnits": 0,
                                "weeksOnHand": 0,
                                "receiveFillRate": 1.0000,
                                "overallVendorLeadTime": 7.26
                            }
                        }
                    ]
                }, { ... }
            ]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# Example Inventory Report (new)

GET_VENDOR_INVENTORY_REPORT

{
  "reportSpecification": {
    "reportType": "GET_VENDOR_INVENTORY_REPORT",
    "reportOptions": {
      "reportPeriod": "WEEK",
      "sellingProgram": "RETAIL",
      "distributorView": "MANUFACTURING"
    },
    "dataStartTime": "2022-05-22",
    "dataEndTime": "2022-05-28",
    "marketplaceIds": [
      "ATVPDKIKX0DER"
    ]
  },
  "inventoryAggregate": [
    {
      "startDate": "2022-05-22",
      "endDate": "2022-05-28",
      "vendorConfirmationRate": 0.88,
      "netReceivedAmount": {
        "amount": 2345.50,
        "currencyCode": "USD"
      },
      "netReceivedUnits": 278,
      "openPurchaseOrderQuantity": 123,
      "overallVendorLeadTime": 10.2,
      "sellThroughRate": 0.88,
      "sellableOnHandInventory": {
        "amount": 43123.99,
        "currencyCode": "USD"
      },
      "sellableOnHandUnits": 5490,
      "unfilledCustomerOrderedUnits": 12,
      "unsellableOnHandInventory": {
        "amount": 2345.50,
        "currencyCode": "USD"
      },
      "unsellableOnHandUnits": 881,
      "aged90PlusDaysSellableInventory": {
        "amount": 123.50,
        "currencyCode": "USD"
      },
      "aged90PlusDaysSellableUnits": 2234,
      "unhealthyInventory": {
        "amount": 123.45,
        "currencyCode": "USD"
      },
      "unhealthyUnits": 114
    },
    { ...
    }
  ],
  "inventoryByAsin": [
    {
      "startDate": "2022-05-22",
      "endDate": "2022-05-28",
      "asin": "B123456789",
      "vendorConfirmationRate": 0.88,
      "netReceivedAmount": {
        "amount": 2345.50,
        "currencyCode": "USD"
      },
      "netReceivedUnits": 278,
      "openPurchaseOrderQuantity": 123,
      "overallVendorLeadTime": 10.2,
      "sellThroughRate": 0.88,
      "sellableOnHandInventory": {
        "amount": 43123.99,
        "currencyCode": "USD"
      },
      "sellableOnHandUnits": 5490,
      "unfilledCustomerOrderedUnits": 12,
      "unsellableOnHandInventory": {
        "amount": 2345.50,
        "currencyCode": "USD"
      },
      "unsellableOnHandUnits": 881,
      "aged90PlusDaysSellableInventory": {
        "amount": 123.50,
        "currencyCode": "USD"
      },
      "aged90PlusDaysSellableUnits": 2234,
      "unhealthyInventory": {
        "amount": 123.45,
        "currencyCode": "USD"
      },
      "unhealthyUnits": 114
    },
    { ...
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
Last Updated: 10/11/2022, 9:45:34 PM