Reports API v2021-06-30 Use Case Guide

sfgoods AmazonSPAPI

# What is the Reports API?

Use the Selling Partner API for Reports (Reports API), to build applications that get reports from Amazon to help selling partners manage their business. The API provides reports for a variety of use cases including: monitoring inventory, tracking orders for fulfillment, getting tax information, tracking returns and seller performance, managing a selling business with Fulfillment by Amazon, and more. Refer to the Reports API Reference (opens new window) for details about Reports API operations and associated data types and schemas. Refer to reportType values (opens new window) for the available report types.

The three principal workflows for generating reports are requesting a report, scheduling a report, and retrieving automatically generated reports.

Requesting a report

You can request any available report type on demand by using the createReport operation. Refer to Tutorial: Request and retrieve a report for instructions.

Scheduling a report

You can have Amazon automatically submit report requests on a schedule using the createReportSchedule operation. Refer to Tutorial: Schedule and retrieve reports for instructions.

Retrieving automatically generated reports

Amazon generates some reports automatically. Refer to Tutorial: Retrieve reports that are automatically generated for instructions for retrieving those automatically generated reports.

# Terminology

S3 pre-signed URL. A URL for an Amazon S3 bucket from which you can download an object without AWS security credentials or permissions.

# Tutorial: Request and retrieve a report

Use the following process for requesting a report:

Call the createReport (opens new window) operation, specifying the type of report and the marketplaces that you are requesting, and any optional parameters.

Amazon receives the report request. If the operation is successful, the response includes a reportId value.
Periodically poll the Amazon SQS queue for REPORT_PROCESSING_FINISHED notification event, which provides information when the report processing is CANCELLED, DONE or FATAL. The notification event includes a reportDocumentId value if there is report data available.
Call the getReportDocument (opens new window) operation, passing the reportDocumentId value from the previous step.

Amazon returns a pre-signed URL for the location of the report document, and the compression algorithm used if the report document contents have been compressed.
Download the report.

# Prerequisites

The following items are required to successfully complete this tutorial:

The report type that you will request. Refer to reportType values (opens new window) for a list of the available report types.
Authorization from the selling partner for whom you are making calls. Refer to the Selling Partner API Developer Guide (opens new window) for more information.
A working Java Development Kit (JDK) installation to run sample code.

Steps

Step 1. Request a report

Step 2. Confirm that the report processing is complete

Step 3. Retrieve the report

# Step 1. Request a report

Request a report by specifying the report type and marketplaces that you are requesting, and any optional parameters.

Call the createReport (opens new window) operation, passing the following parameters:

Request body:

Name	Description	Required
reportOptions	Additional information passed to reports. This varies by report type. Type: ReportOptions	No
reportType	The report type. For more information, see reportType values. Type: string	Yes
dataStartTime	The start of a date and time range, in ISO 8601 date time format, used for selecting the data to report. The default is now. The value must be prior to or equal to the current date and time. Not all report types make use of this. Type: string (date-time)	No
dataEndTime	The end of a date and time range, in ISO 8601 date time format, used for selecting the data to report. The default is now. The value must be prior to or equal to the current date and time. Not all report types make use of this. Type: string (date-time)	No
marketplaceIds	A list of marketplace identifiers. The report document's contents will contain data for all of the specified marketplaces, unless the report type indicates otherwise. Type: < string > array	Yes

# Request example:

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports
{
  "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
  "dataStartTime": "2019-12-10T20:11:24.000Z",
  "marketplaceIds": [
    "A1PA6795UKMFR9",
    "ATVPDKIKX0DER"
  ]
}

1
2
3
4
5
6
7
8
9

Response

A successful response includes the following property:

Name	Description
reportId	The identifier for the report. This identifier is unique only in combination with a seller ID. Type: string

# Response example:

{
  "reportId": "ID323"
}

1
2
3

# Step 2. Confirm that the report processing is complete

To confirm that the report processing is complete, refer to How to verify that the report processing is complete.

# Step 3. Retrieve the report

To retrieve the report, refer to How to retrieve a report.

# Tutorial: Schedule and retrieve reports

You can schedule requests for reports so that they are submitted periodically, using the createReportSchedule operation. Use the period enumeration to specify the time period. To identify which reports can be scheduled, review the Report Type Values (opens new window) in the Selling Partner API documentation.

Use the following process for requesting a report:

Call the createReportSchedule (opens new window) operation to create a schedule for periodically submitting report requests. Specify reportType, marketplaceIds and period values and any optional parameters. For reportType values, refer to reportType values (opens new window). For period values, refer to period enumeration (opens new window).

Note: If a report schedule with the same report type and marketplace IDs already exists, it is cancelled and replaced with this schedule. Otherwise, a new report schedule is created.
Periodically poll the Amazon SQS queue for REPORT_PROCESSING_FINISHED notification event using an interval that is similar to the schedule that you configured in the first step.

If you receive a notification for the scheduled report, the notification event contains report information, including reportDocumentId value if report data is available.
For each reportDocumentId:
1. Call the getReportDocument (opens new window) operation, passing the reportDocumentId value.
  
  Amazon returns a pre-signed URL for the location of the report document, and the compression algorithm used if the report document contents have been compressed.
2. Download the report.

# Prerequisites

The following items are required to successfully complete this tutorial:

A report type to schedule. Refer to reportType values (opens new window) for a list of the available report types.
Authorization from the selling partner for whom you are making calls. Refer to the Selling Partner API Developer Guide (opens new window) for more information.
A working Java Development Kit (JDK) installation to run sample code.

Steps

Step 1. Create a schedule for report requests

Step 2. Periodically retrieve information about the scheduled reports

Step 3. Retrieve the report

# Step 1. Create a schedule for report requests

Call the createReportSchedule operation to create a schedule for submitting report requests, specifying the reportType, markeplaceIds, and period values and any optional parameters. Refer to reportType values (opens new window) for a list of the available report types.

Call the createReportSchedule (opens new window) operation and pass the following parameters:

Body parameter:

Name	Description	Required
reportType	The report type. Type: string	Yes
marketplaceIds	A list of marketplace identifiers for the report schedule. Type: < string > array	Yes
reportOptions	Additional information passed to reports. This varies by report type. Type: ReportOptions	No
period	One of a set of predefined ISO 8601 periods that specifies how often a report should be created. Type: enum (Period)	Yes
nextReportCreationTime	The date and time when the schedule will create its next report, in ISO 8601 date time format. Type: string (date-time)	No

# Request example:

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/schedules
{
  "reportType": "GET_XML_BROWSE_TREE_DATA",
  "period": "P2D",
  "marketplaceIds":["ATVPDKIKX0DER"]
}

1
2
3
4
5
6

Response

A successful response includes the following:

Name	Description	Schema
CreateReportScheduleResponse	The payload for the createReportSchedule operation.	CreateReportScheduleResponse

# Response example:

{
  "reportScheduleId": "ID323"
}

1
2
3

# Step 2. Periodically retrieve information about the scheduled reports

Periodically poll the Amazon SQS queue for REPORT_PROCESSING_FINISHED notification event using an interval that is similar to the schedule that you configured in step 1. To confirm that report processing is complete, refer to How to verify that the report processing is complete.

# Step 3. Retrieve the report

To retrieve a report, refer to How to retrieve a report.

# Tutorial: Retrieve reports that are automatically generated

Use the following process for requesting an automatically generated report:

Periodically poll the Amazon SQS queue for REPORT_PROCESSING_FINISHED notification event which provides information when the report processing is CANCELLED, DONE or FATAL. The notification event includes a reportDocumentId value if there is report data available.
For each reportDocumentId that represents a report that you want to retrieve:
1. Call the getReportDocument (opens new window) operation, passing the reportDocumentId value.
  
  Amazon returns a pre-signed URL for the location of the report document, and the compression algorithm used if the report document contents have been compressed.
2. Download the report.

# Prerequisites

The following items are reuqired to successfully complete this tutorial:

One or more report types to download after the report data is available. Refer to reportType values (opens new window) for a list of report types.
Authorization from the selling partner for whom you are making calls. Refer to the Selling Partner API Developer Guide (opens new window) for more information.
A working Java Development Kit (JDK) installation to run sample code.

Steps

Step 1. Retrieve information about reports that can be downloaded

Step 2. Retrieve the report

# Step 1. Retrieve information about reports that can be downloaded

You can periodically poll the Amazon SQS queue to check if you have received a notification regarding the Amazon generated reports. To confirm that report processing is complete, refer to How to verify that the report processing is complete.

The REPORT_PROCESSING_FINISHED notification event contains the reportDocumentId, which can be used to download the report.

For each reportDocumentId that represents a report that you want to retrieve, save the reportDocumentId and go to Step 2 to retrieve the report.

# Response example:

{
  "reports": [
    {
      "reportType": "GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE",
      "processingEndTime": "2021-08-03T01:02:25+00:00",
      "processingStatus": "DONE",
      "marketplaceIds": [
        "ATVPDKIKX0DER"
      ],
      "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
      "reportId": "ID222",
      "dataEndTime": "2021-08-03T01:02:25+00:00",
      "createdTime": "2021-08-03T01:02:25+00:00",
      "processingStartTime": "2021-08-03T01:02:25+00:00",
      "dataStartTime": "2021-08-03T01:02:25+00:00"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Step 2. Retrieve the report

To retrieve a report, refer to How to retrieve a report.

# How to verify that the report processing is complete

We recommend that you use the Notifications API (opens new window) to subscribe to the REPORT_PROCESSING_FINISHED event in order to be notified when the report processing status changes. This reduces the number of calls you make to getReport (opens new window) or getReports (opens new window) for processing status checks.

The REPORT_PROCESSING_FINISHED notification event is sent when any report reaches a processing status of DONE, CANCELLED, or FATAL.

To subscribe to the REPORT_PROCESSING_FINISHED notification type,refer to the Notifications API Use Case Guide (opens new window). For more information, refer to REPORT_PROCESSING_FINISHED notification event (opens new window).

The following processingStatus values confirm that processing has ended:

CANCELLED - The report was cancelled. There are two ways a report can be cancelled: 1) a cancellation request before the report starts processing, or 2) an automatic cancellation if there is no data to return.
DONE - The report has completed processing and a reportDocumentId is available.
FATAL - The report was abandoned due to a fatal error and a reportDocumentId may be present. If present, the report represented by the reportDocumentId may explain why the report processing ended.

# How to retrieve a report

Get the information required to retrieve a report document and then download the report.

Steps

Step 1. Get the information required to retrieve the report

Step 2. Download the report

# Step 1. Get the information required to retrieve the report

Call the getReportDocument operation to get the information required for retrieving a report document's contents. This includes a pre-signed URL for the report document and optionally, the compression algorithm used if the report document contents have been compressed.

Call the getReportDocument (opens new window) operation, passing the following parameter:

Path parameter:

Name	Description	Required
reportDocumentId	The identifier for the report document. Type: string	Yes

# Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/documents/DOC-b8b0-4226-b4b9-0ee058ea5760

Response

A successful response includes the following:

Name	Description
reportDocumentId	The identifier for the report document. This identifier is unique only in combination with a seller ID.
url	A pre-signed URL for the report document. This URL expires after 5 minutes. Type: string
compressionAlgorithm	If present, the report document contents have been compressed with the provided algorithm. Type: enum (CompressionAlgorithm)

# Response example:

{
  "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
  "url": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8"
}

1
2
3
4

Save the url, and compressionAlgorithm (optional property) for use in Step 2.

# Step 2. Download the report

You must download the report using the information returned in Step 1. The following sample code demonstrates how to download a plain text report document. You can also use the principles demonstrated in the sample code to guide you in building applications in other programming languages, or for other types of documents (XML,CSV,TSV, etc.).

Use the following as inputs for the sample code:
- The url and optional compressionAlgorithm values from the previous step are arguments for the url, and compressionAlgorithm parameters of the download method of the DownloadExample class.

Note: You must always maintain encryption at rest. Unencrypted report content must never be stored on disk, even temporarily, because reports can contain sensitive information. The sample code that we provide demonstrates this principle.

# Sample Code (Java)

// DownloadExample.java
// This example is for use with the Selling Partner API for Reports, Version: 2021-06-30
// and the Selling Partner API for Feeds, Version: 2021-06-30
import java.io.BufferedReader;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import java.util.zip.GZIPInputStream;

import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.ResponseBody;

/**
 * Example that downloads a document.
 */
public class DownloadExample {

  public static void main(String args[]) {
    String url = "<URL from the getFeedDocument/getReportDocument response>";
    String compressionAlgorithm = "<compressionAlgorithm from the getFeedDocument/getReportDocument response>";

    DownloadExample obj = new DownloadExample();
    try {
      obj.download(url, compressionAlgorithm);
    } catch (IOException e) {
      //Handle exception here.
    } catch (IllegalArgumentException e) {
      //Handle exception here.
    }
  }

  /**
   * Download and optionally decompress the document retrieved from the given url.
   *
   * @param url                  the url pointing to a document
   * @param compressionAlgorithm the compressionAlgorithm used for the document
   * @throws IOException              when there is an error reading the response
   * @throws IllegalArgumentException when the charset is missing
   */
  public void download(String url, String compressionAlgorithm) throws IOException, IllegalArgumentException {
    OkHttpClient httpclient = new OkHttpClient();
    Request request = new Request.Builder()
      .url(url)
      .get()
      .build();

    Response response = httpclient.newCall(request).execute();
    if (!response.isSuccessful()) {
      System.out.println(
        String.format("Call to download content was unsuccessful with response code: %d and message: %s",
          response.code(), response.message()));
      return;
    }

    try (ResponseBody responseBody = response.body()) {
      MediaType mediaType = MediaType.parse(response.header("Content-Type"));
      Charset charset = mediaType.charset();
      if (charset == null) {
        throw new IllegalArgumentException(String.format(
          "Could not parse character set from '%s'", mediaType.toString()));
      }

      Closeable closeThis = null;
      try {
        InputStream inputStream = responseBody.byteStream();
        closeThis = inputStream;

        if ("GZIP".equals(compressionAlgorithm)) {
          inputStream = new GZIPInputStream(inputStream);
          closeThis = inputStream;
        }

        // This example assumes that the download content has a charset in the content-type header, e.g.
        // text/plain; charset=UTF-8
        if ("text".equals(mediaType.type()) && "plain".equals(mediaType.subtype())) {
          InputStreamReader inputStreamReader = new InputStreamReader(inputStream, charset);
          closeThis = inputStreamReader;

          BufferedReader reader = new BufferedReader(inputStreamReader);
          closeThis = reader;

          String line;
          do {
            line = reader.readLine();
            // Process line by line.
          } while (line != null);
        } else {
          //Handle content with binary data/other media types here.
        }
      } finally {
        if (closeThis != null) {
          closeThis.close();
        }
      }
    }
  }
}

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
93
94
95
96
97
98
99
100
101
102

# Best practices

# Expect changes to reports

Amazon periodically adds new fields and field values to reports. Ensure that any report parsers that you build into your applications can gracefully handle these types of report updates.

# Don't rely on document ID structure

Do not rely on the format and structure of document identifiers. The format and structure is subject to change.

Reports API v2020-09-04 Solicitations API v1

Amazon Selling Partner API - spapi.cyou

Choose mode