Tutorial: Request a report
Request reports from Amazon to help selling partners manage their business.
API Version: 2021-06-30
Tutorial: Request and retrieve a report
Use the following process for requesting a report:
- Call the
createReport
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 isCANCELLED
,DONE
orFATAL
. The notification event includes areportDocumentId
value if there is report data available. -
Call the
getReportDocument
operation, passing thereportDocumentId
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 Report Type 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.
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:
Name | Description | Required |
---|---|---|
reportOptions |
Additional information passed to reports. This varies by report type. Type: |
No |
reportType |
The report type. For more information, refer to Report Type 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"
]
}
Response
A successful response includes the following properties:
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"
}
Step 2. Confirm that the report processing is complete
To confirm that the report processing is complete, refer to Verify that the report processing is complete.
Step 3. Retrieve the report
To retrieve the report, refer to Retrieve a report.
Tutorial: Request and retrieve a bulk invoice report for MCF orders for India
Use the following process to request a report:
- Call the
createReport
operation, specifying the type of report, 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 the
REPORT_PROCESSING_FINISHED
notification event, which provides information when the report processing isCANCELLED
,DONE
orFATAL
. The notification event includes areportDocumentId
value if there is report data available. -
Call the
getReportDocument
operation, passing thereportDocumentId
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 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.
Step 1. Request a report
Request a report by specifying the report type, the marketplaces that you are requesting, and any optional parameters.
Call the createReport
operation, passing the following parameters:
Request body:
Name | Description | Required |
---|---|---|
reportOptions |
Additional information passed to reports. This varies by report type. Type: |
No |
reportType |
The report type. The value must be 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 or equal to the current date and time. Not all report types make use of this parameter. 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 or equal to the current date and time. Not all report types make use of this parameter. 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
{
"marketplaceIds": [
"A2XZLSVIQ0F4JT"
],
"reportType": "FBA_BULK_INVOICE",
"dataEndTime": "2023-05-27T23:59:59+00:00",
"dataStartTime": "2023-05-22T00:00:00+00:00"
}
Response
A successful response includes the following properties:
Name | Description |
---|---|
reportId
|
The identifier for the report. This identifier is unique only in combination with a seller ID. Type: string |
Response example:
{
"reportId": "51665019712"
}
Step 2. Confirm that the report processing is complete
To confirm that the report processing is complete, refer to Verify that the report processing is complete.
Step 3. Retrieve the report
To retrieve the report, refer to Retrieve a report.
Updated about 1 month ago