HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Tutorial: Schedule and Retrieve Reports

Schedule and retrieve reports from Amazon to help selling partners manage their business.

API Version: 2021-06-30

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 in the Selling Partner API documentation.

Use the following process to request a report:

  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, refer to reportType values. For period values, refer to period enumeration.

    📘

    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.

  2. 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.

  3. For each reportDocumentId:

    1. Call the getReportDocument 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 for a list of the available report types.

  • Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

  • A working Java Development Kit (JDK) installation to run sample code.

Steps

  1. Create a schedule for report requests

  2. Periodically retrieve information about the scheduled reports

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

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"]
}

Response

A successful response includes the following:

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

Response example:

{
  "reportScheduleId": "ID323"
}

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 the REPORT_PROCESSING_FINISHED notification event.

Step 3. Retrieve the report

To retrieve a report, refer to Retrieve a report.