API Version: 2020-09-04

What is the Reports API?

Effective June 27, 2023, the Selling Partner API for Reports v2020-09-04 will no longer be available and all calls to it will fail. Integrations that rely on the Reports API must migrate to Reports v2021-06-30 to avoid service disruption.

Terminology

• Cipher block chaining. Cipher block chaining is an algorithm that uses a block cipher to provide information security such as confidentiality or authenticity. This algorithm uses an initialization vector and a key to encrypt the data.

• Amazon S3 presigned URL. A URL for an S3 bucket from which you can download an object without AWS security credentials or permissions. In some cases the object may be compressed, in which case compressionAlgorithm is returned in addition to the URL. The URL expires after 5 minutes.

Tutorial: Request and retrieve a report

Here are the high-level steps for requesting a report:

1. Call the createReport operation, specifying the type of report and the marketplaces that you are requesting, and any optional parameters that you want.

   Amazon receives the report request. If the operation is successful, the response includes a reportId value.

2. Periodically call the getReport operation, passing the reportId value from the previous step, until the processingStatus value in the response indicates that processing has ended. Processing will have ended when the processingStatus equals CANCELLED, DONE or FATAL. At this point the response includes a reportDocumentId value if there is report data available.

3. Call the getReportDocument operation, passing the reportDocumentId value from the previous step.

   Amazon returns a presigned URL for the location of the report document along with the encryption details. In some cases the object may be compressed, in which case compressionAlgorithm is returned in addition to the URL. The URL expires after 5 minutes.

4. Download and decrypt the report.

Prerequisites

To complete this tutorial, you will need:

• A report type to request. See reportType values for a list of the available report types.

• Authorization from the seller for whom you are making calls. See the Selling Partner API Developer Guide for more information.

• An understanding of client-side encryption using the cipher block chaining (CBC). For definitions, see Terminology.

• To use the sample code in this guide, a working Java Development Kit (JDK) installation, including the javax.crypto library.

Steps

1. Request a report

2. Confirm report processing has completed

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 operation, passing the following parameters:

Request body:

Request example:

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

Response

A successful response includes the following property:

Response example:

{
  "payload":
  {
    "reportId": "ID323"
  }
}

Step 2. Confirm that report processing has completed

After you call the createReport operation, Amazon receives the request and begins processing the report. You must then confirm that processing has completed before you continue.

Periodically call the getReport operation, passing the reportId value from the previous step, until the processingStatus value in the response indicates that processing has ended. Processing will have ended when the processingStatus equals CANCELLED, DONE or FATAL. At this point the response includes a reportDocumentId value if there is report data available.

Here are the processingStatus values that confirm that processing has ended:

• CANCELLED - The report was cancelled. There are two ways a report can be cancelled: an explicit cancellation request before the report starts processing, or 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 stopped 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.

The following processingStatus values indicate that processing has not ended, and you should continue to call the getReport operation until the operation returns a processingStatus of CANCELLED, DONE or FATAL.

• IN_PROGRESS - The report is being processed.

• IN_QUEUE - The report has not yet started processing. It may be waiting for another IN_PROGRESS report.

Note: The getReport operation only serves information for on-demand or scheduled report requests that were created within the last 90 days.

Path parameter:

Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports/ID323

Response

A successful response includes the following:

Response example

{
  "payload": {
    "reportId": "ID323",
    "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
    "dataStartTime": "2019-12-11T13:47:20.677Z",
    "dataEndTime": "2019-12-12T13:47:20.677Z",
    "createdTime": "2019-12-10T13:47:20.677Z",
    "processingStatus": "DONE",
    "processingStartTime": "2019-12-10T13:47:20.677Z",
    "processingEndTime": "2019-12-12T13:47:20.677Z",
    "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760"
  }
}

Step 3. Retrieve the report

To retrieve the report, see 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 reportType values in the Selling Partner API documentation.

Here are the high-level steps for scheduling and retrieving reports:

1. Call the createReportSchedule operation to create a schedule for periodically submitting report requests. Specify reportType, marketplaceIds and period values and any optional parameters. For reportType values, see reportType values. For period values, see period enumeration.

   Note: If a report schedule with the same report type and marketplace IDs already exists, it will be cancelled and replaced with this one. Otherwise a new report schedule will be created.

2. Periodically call the getReports operation using an interval that is similar to the schedule that you configured in the previous step.

   If a call to the getReports operation succeeds, the response contains an array of report information, including reportDocumentId values if report data is available.

   Note: The getReports operation only serves information for on-demand or scheduled report requests that were created within the last 90 days.

3. For each reportDocumentId:

   1. Call the getReportDocument operation, passing the reportDocumentId value.

      Amazon returns a presigned URL for the location of the report document along with the encryption details. In some cases the object may be compressed, in which case compressionAlgorithm is returned in addition to the URL. The URL expires after 5 minutes.

   2. Download and decrypt the report.
      

Prerequisites

To complete this tutorial, you will need:

• A report type to schedule. See reportType values for a list of the available report types.

• Authorization from the seller for whom you are making calls. See the Selling Partner API Developer Guide for more information.

• An understanding of client-side encryption using the cipher block chaining (CBC). For definitions, see Terminology.

• To use the sample code in this guide, a working Java Development Kit (JDK) installation, including the javax.crypto library.

Steps

1. Create a schedule for report requests

2. Periodically retrieve information about the scheduled reports

3. Retrieve the reports

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. See reportType values for a list of the available report types.

• Call the createReportSchedule operation and pass the following parameters:

Body parameter:

Request example:

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

Response

A successful response includes the following:

Response example:

{
  "payload":
  {
    "reportScheduleId": "ID323"
  }
}

Step 2: Periodically retrieve information about the scheduled reports

Periodically call the getReports operation using an interval that is similar to the schedule that you configured. You'll want to try to time these calls so that they occur after scheduled reports are likely to have been completed.

1. Call the getReports operation periodically to retrieve information about scheduled reports, passing the following parameters:

Query parameters:

Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports?reportTypes=GET_XML_BROWSE_TREE_DATA

Response

A successful response includes the following:

The payload array in the response contains one Report object (see Report for each processed report, and each Report object contains the reportDocumentId.

Note: Information about both on-demand and scheduled reports is returned. To identify scheduled reports, look for the presence of a reportScheduleId in the Report object in the response. The reportScheduleId indicates which schedule submitted this report request.

2. For each reportDocumentId, save the reportDocumentId and go to Step 3 to retrieve the report.

Response example:

{
  "nextToken": "VGhpcyB0b2tlbiBpcyBvcGFxdWUgYW5kIGludGVudGlvbmFsbHkgb2JmdXNjYXRlZA==",
  "payload": [
    {
      "reportType": "GET_XML_BROWSE_TREE_DATA",
      "processingEndTime": "2020-09-23T22:52:59+00:00",
      "processingStatus": "DONE",
      "marketplaceIds": ["ATVPDKIKX0DER"],
      "reportDocumentId": "FOO_eae0a7b7-6c33-4191-ad1a-f31ac1ae0ce3",
      "reportId": "ID222",
      "dataEndTime": "2020-09-23T22:52:24+00:00",
      "createdTime": "2020-09-23T22:52:43+00:00",
      "processingStartTime": "2020-09-23T22:52:49+00:00",
      "reportScheduleId": "ID323",
      "dataStartTime": "2020-09-23T22:37:24+00:00"
    }
  ]
}

Step 3: Retrieve the report

To retrieve a report, see How to Retrieve a Report.

How to Retrieve a Report

Get your report by first getting the information required to retrieve a report document and then downloading and decrypting the report.

Steps

1. Get information required to retrieve the report

2. Download and decrypt the report

Step 1. Get 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 presigned URL for the report document as well as the information required to decrypt the document's contents. In some cases the object may be compressed, in which case compressionAlgorithm is returned in addition to the URL. The URL expires after 5 minutes.

1. Call the getReportDocument operation, passing the following parameter:

Path parameter:

Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/documents/DOC-b8b0-4226-b4b9-0ee058ea5760

Response

A successful response includes the following elements:

Response example:

{
  "payload": {
    "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",
    "encryptionDetails": {
      "standard": "AES",
      "initializationVector": "58 fa bf a7 08 11 95 0f c1 a8 c6 e0 d5 6f ae c8",
      "key": "Sample"
    }
  }
}

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

Step 2. Download and decrypt the report

You will need to download and decrypt the report using the information returned in the previous step. The following sample code along with the classes provided in the Selling Partner API Documents Helper can help. You can also use the principles demonstrated in the sample code and in the SP-API Documents Helper code to guide you in building applications in other programming languages.

1. Use the following as inputs for the sample code:

   • The key, initializationVector, url, and optional compressionAlgorithm values from the previous step are arguments for the key, initializationVector, url, and compressionAlgorithm parameters of the downloadAndDecrypt method of the DownloadExample class.

Note: It's the developer's responsibility to always maintain encryption at rest. Unencrypted report content should 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
import java.io.BufferedReader;
import java.io.IOException;

import com.amazon.spapi.documents.CompressionAlgorithm;
import com.amazon.spapi.documents.DownloadBundle;
import com.amazon.spapi.documents.DownloadHelper;
import com.amazon.spapi.documents.DownloadSpecification;
import com.amazon.spapi.documents.exception.CryptoException;
import com.amazon.spapi.documents.exception.HttpResponseException;
import com.amazon.spapi.documents.exception.MissingCharsetException;
import com.amazon.spapi.documents.impl.AESCryptoStreamFactory;

public class DownloadExample {
  final DownloadHelper downloadHelper = new DownloadHelper.Builder().build();

  // The key, initializationVector, url, and compressionAlgorithm are obtained from the response to
  // the getReportDocument operation.
  public void downloadAndDecrypt(String key, String initializationVector, String url, String compressionAlgorithm) {
    AESCryptoStreamFactory aesCryptoStreamFactory =
      new AESCryptoStreamFactory.Builder(key, initializationVector).build();

    DownloadSpecification downloadSpec = new DownloadSpecification.Builder(aesCryptoStreamFactory, url)
      .withCompressionAlgorithm(CompressionAlgorithm.fromEquivalent(compressionAlgorithm))
      .build();

    try (DownloadBundle downloadBundle = downloadHelper.download(downloadSpec)) {
      // This example assumes that the downloaded file has a charset in the content type, e.g.
      // text/plain; charset=UTF-8
      try (BufferedReader reader = downloadBundle.newBufferedReader()) {
        String line;
        do {
          line = reader.readLine();
          // Process the decrypted line.
        } while (line != null);
      }
    }
    catch (CryptoException | HttpResponseException | IOException | MissingCharsetException e) {
        // Handle exception here.
    }
  }
}

Best practices

Expect changes to reports

Amazon periodically adds new fields and field values to reports. Be sure 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

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