Document API static sandbox guide

The Document API supports the Amazon Business API static sandbox. The static sandbox uses pattern matching to return static, mocked responses.

You can use the sandbox environment to securely test your integration with the Document API before moving to production. By sending requests to the sandbox endpoints instead of production endpoints, you can test standard workflows without triggering real-world events.

Prerequisites

Before calling the Document API static sandbox, complete the steps in Accessing the Amazon Business API sandbox environment to create a sandbox app and generate a sandbox API access token.

Once you’ve generated the access token, direct each sandbox call to the appropriate Amazon Business API sandbox endpoint for your region.

Sandbox scenarios

Use the following sample requests to test the success and error scenarios in the Document API static sandbox. If you use input parameters other than the sample values below, an error will occur.

Path: POST /reports/2021-09-30/reports

Scenario: Calling Document API sandbox createReport operation to post the report with the report type, data start time, and marketplace identifiers for the report:

POST https://sandbox.na.business-api.amazon.com/reports/2021-09-30/reports

{
    "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
    "dataStartTime": "2019-12-10T20:11:24.000Z",
    "marketplaceIds": [
        "A1PA6795UKMFR9",
        "ATVPDKIKX0DER"
    ]
}

Response: A successful response returns a 200 status code with a reportId of ID323 in response body.

Status code: 200 OK

{
    "reportId": "ID323"
}

Scenario: Calling Document API sandbox createReport operation to post the report with an invalid report type:

POST https://sandbox.na.business-api.amazon.com/reports/2021-09-30/reports

{
    "reportType": "BAD_FEE_DISCOUNTS_REPORT",
    "dataStartTime": "2019-12-10T20:11:24.000Z",
    "marketplaceIds": [
        "A1PA6795UKMFR9",
        "ATVPDKIKX0DER"
    ]
}

Response: This scenario returns a 400 status code with an “Invalid request parameters” error message.

Response code: 400 Bad Request

{
    "errors": [
        {
            "code": "400",
            "message": "Invalid request parameters",
            "details": "The system encountered an invalid input while processing the request. Please provide all the required parameters to complete the request."
        }
    ]
}

Path: GET /reports/2021-09-30/reports/{reportId}

Scenario: Calling Document API sandbox getReport operation to get a report with the valid ID323 report ID:

GET https://sandbox.na.business-api.amazon.com/reports/2021-09-30/reports/ID323

Response: A successful request returns a 200 response code with the report status in response body. The processingStatus will be IN_PROGRESS.

Response code: 200 OK

{
    "reportId": "ID323",
    "reportType": "FEE_DISCOUNTS_REPORT",
    "dataStartTime": "2019-12-11T13:47:20.677Z",
    "dataEndTime": "2019-12-12T13:47:20.677Z",
    "createdTime": "2019-12-10T13:47:20.677Z",
    "processingStatus": "IN_PROGRESS",
    "processingStartTime": "2019-12-10T13:47:20.677Z",
    "processingEndTime": "2019-12-12T13:47:20.677Z"
}

Scenario: Calling Document API sandbox getReport operation to get the report from an invalid report ID:

GET https://sandbox.na.business-api.amazon.com/reports/2021-09-30/reports/badReportId1

Response: This scenario returns a 400 status code with an “Invalid request parameters” error message.

Response code: 400 Bad Request

{
    "errors": [
        {
            "code": "400",
            "message": "Invalid request parameters",
            "details": "Invalid input in processing status, please make sure to provide all the required parameters to complete the request."
        }
    ]
}

Path: GET /reports/2021-09-30/documents/{reportDocumentId}

Scenario: Calling Document API sandbox getReportDocument operation to get the document with a proper document ID:

GET https://sandbox.na.business-api.amazon.com/reports/2021-09-30/documents/0356cf79-b8b0-4226-b4b9-0ee058ea5760

Response: A successful request returns a 200 response code with the reportDocumentId and a url to the document in the response body.

Response code: 200 OK

{
    "reportDocumentId": "0356cf79-b8b0-4226-b4b9-0ee058ea5760",
    "url": "https://d34o8swod1owfl.cloudfront.net/Report_47700__GET_MERCHANT_LISTINGS_ALL_DATA_.txt"
}

Scenario: Calling Document API sandbox getReportDocument operation to get the document without a proper document ID:

GET https://sandbox.na.business-api.amazon.com/reports/2021-09-30/documents/badDocumentId1

Response: This scenario returns a 400 status code with an “Invalid request parameters” error message.

Response code: 400 Bad Request

{
    "errors": [
        {
            "code": "400",
            "message": "Invalid request parameters",
            "details": "The system encountered an invalid input while processing the request. Please provide all the required parameters to complete the request."
        }
    ]
}

Path: GET /reports/2021-09-30/reports

Scenario: Calling Document API sandbox getReports operation to retrieve an array of reports filtered by a valid list of report types and processing statuses:

GET https://sandbox.na.business-api.amazon.com/reports/2021-09-30/reports?reportTypes=FEE_DISCOUNTS_REPORT,GET_AFN_INVENTORY_DATA&processingStatuses=IN_QUEUE,IN_PROGRESS

Response: A successful request returns a 200 response code with a reports object containing one report, ReportId1, in the response body.

Response code: 200 OK

{
    "nextToken": "VGhpcyB0b2tlbiBpcyBvcGFxdWUgYW5kIGludGVudGlvbmFsbHkgb2JmdXNjYXRlZA==",
    "reports": [
        {
            "reportId": "ReportId1",
            "reportType": "FEE_DISCOUNTS_REPORT",
            "dataStartTime": "2019-12-11T13:47:20.677Z",
            "dataEndTime": "2019-12-12T13:47:20.677Z",
            "createdTime": "2019-12-10T13:47:20.677Z",
            "processingStatus": "IN_PROGRESS",
            "processingStartTime": "2019-12-10T13:47:20.677Z",
            "processingEndTime": "2019-12-12T13:47:20.677Z"
        }
    ]
}

Scenario: Calling Document API sandbox getReports operation to retrieve an array of reports filtered by valid report types and an invalid processing status:

GET https://sandbox.na.business-api.amazon.com/reports/2021-09-30/reports?reportTypes=FEE_DISCOUNTS_REPORT,GET_AFN_INVENTORY_DATA&processingStatuses=BAD_VALUE,IN_PROGRESS

Response: This scenario returns a 400 status code with an “Invalid request parameters” error message.

Response code: 400 Bad Request

{
    "errors": [
        {
            "code": "400",
            "message": "Invalid request parameters",
            "details": "The system encountered an invalid input while processing the request. Please provide all the required parameters to complete the request."
        }
    ]
}