Vendor Retail Analytics Reports Migration Guide

sfgoods 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

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).
Use the getReport and getReportDocument API operations to download the reports.
Review the structure and content of the reports.

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

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

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

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.

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.

Update your createReport request to use the new reportType value (for example, GET_VENDOR_SALES_REPORT).
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

Old		New
Report Type Value	Data Element	Report	Data Element(s)	Notes
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	preOrderedReveue	n/a	n/a	Deprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	preOrderedUnits	n/a	n/a	Deprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	orderedRevenue	GET_VENDOR_SALES_REPORT	orderedRevenue
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	orderedUnits	GET_VENDOR_SALES_REPORT	orderedUnits
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	shippedRevenue	GET_VENDOR_SALES_REPORT	shippedRevenue
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	shippedUnits	GET_VENDOR_SALES_REPORT	shippedUnits
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	shippedCogs	GET_VENDOR_SALES_REPORT	shippedCogs
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	glanceViews	GET_VENDOR_TRAFFIC_REPORT	glanceViews
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	conversionRate	n/a	n/a	Deprecated but can be calculated: orderedUnits / glanceViews
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	lostBuyBox	n/a	n/a	Deprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	customerReturns	n/a	n/a	Deprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	freeReplacements	n/a	n/a	Deprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	orderedSubcategorySalesRank	n/a	n/a	Deprecated
GET_VENDOR_SALES_DIAGNOSTIC_REPORT	shippedSubcategorySalesRank	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	netReceivedAmount	GET_VENDOR_INVENTORY_REPORT	netReceivedAmount
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	netReceivedUnits	GET_VENDOR_INVENTORY_REPORT	netReceivedUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	openPurchaseOrderQuantity	GET_VENDOR_INVENTORY_REPORT	openPurchaseOrderQuantity
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	sellThroughRate	GET_VENDOR_INVENTORY_REPORT	sellThroughRate
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	sellableOnHandInventory	GET_VENDOR_INVENTORY_REPORT	sellableOnHandInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	sellableOnHandAmountTrailing30DayAverage	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	sellableOnHandUnits	GET_VENDOR_INVENTORY_REPORT	sellableOnHandUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unsellableOnHandInventory	GET_VENDOR_INVENTORY_REPORT	unsellableOnHandInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unsellableOnHandAmountTrailing30DayAverage	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unsellableOnHandUnits	GET_VENDOR_INVENTORY_REPORT	unsellableOnHandUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	aged90PlusDaysSellableInventory	GET_VENDOR_INVENTORY_REPORT	aged90PlusDaysSellableInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	aged90PlusDaysSellableAmountTrailing30DayAverage	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	aged90PlusDaysSellableUnits	GET_VENDOR_INVENTORY_REPORT	aged90PlusDaysSellableUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unhealthyInventory	GET_VENDOR_INVENTORY_REPORT	unhealthyInventory
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unhealthyUnitsTrailing30DayAverage	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	availableUnits	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unhealthyUnits		unhealthyUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	unfilledCustomerOrderedUnits		unfilledCustomerOrderedUnits
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	weeksOnHand	n/a	n/a	Deprecated
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	receiveFillRate	n/a	n/a	Deprecated. See vendorConfirmationRate
GET_VENDOR_INVENTORY_HEALTH_AND_PLANNING_REPORT	overallVendorLeadTime		overallVendorLeadTime
GET_VENDOR_DEMAND_FORECAST_REPORT	relativeWeek	GET_VENDOR_FORECASTING_REPORT	startDate and endDate	Use startDate and endDate to calculate the week relative to the forecastGenerationDate
GET_VENDOR_DEMAND_FORECAST_REPORT	demandForecastType and demandUnits	GET_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

Vendor Direct Fulfillment Dynamic Sandbox Guide Viewing your application information and credentials

Amazon Selling Partner API - spapi.cyou

Choose mode