Retrieving order reports by purchase order number

Reporting API allows you to retrieve order information using a specific purchase order number with the getOrderReportsByPurchaseOrderNumber operation. This operation can help track orders associated with a particular purchase order, enabling in-depth reporting and analysis.

Prerequisites

Complete the API onboarding process to register as a developer, create an app client, and retrieve API access and refresh tokens. For more information, see Onboarding overview.
Gain access to the Amazon Business Analytics role. For more information, see Amazon Business API roles.

Step 1. Retrieve order reports

Call the getOrderReportsByPurchaseOrderNumber operation to retrieve order reports associated with a specific purchase order number. Optionally, you can pass theregion query parameter to filter order results. In the request, include the following parameters:

Type	Name	Description	Schema	Required
path	`purchaseOrderNumber`	The purchase order number used to retrieve associated orders.	string	Yes
query	`region`	The region where the order was placed. If the business has not placed orders in that region or does not belong to that region, the result would be empty.	string	Yes
query	`nextPageToken`	A page token returned in the response to your previous request when the number of results exceed the page size.	string	No

GET https://na.business-api.amazon.com/reports/2025-06-09/purchaseOrders/PoNumber1/orderReports?region=US

import requests

url = "https://na.business-api.amazon.com/reports/2025-06-09/purchaseOrders/PoNumber1/orderReports?region=US"

headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
}

response = requests.get(url, headers=headers)

print(response.text)

A successful response includes the following fields:

Name	Description	Schema	Required
`ordersReport`	The list of orders matching the search criteria.	< OrderReport > array	Yes
`nextPageToken`	A token to retrieve the next page of results.	string	Yes
`size`	Number of orders in the response.	integer	No

📘
Each Reporting API request can return a maximum of 100 results.

{
    "ordersReport": [
        {
            "orderMetadata": {
                "orderDate": "2024-11-08T21:29:44Z",
                "orderId": "114-0575598-4117065",
                "region": "US"
            },
            "purchaseOrderNumber": "PoNumber1",
            "charges": [
                {
                    "type": "SUBTOTAL",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 2.65
                    }
                },
                {
                    "type": "SHIPPING_AND_HANDLING",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 0.0
                    }
                },
                {
                    "type": "PROMOTION",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 0.0
                    }
                },
                {
                    "type": "TAX",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 0.27
                    }
                },
                {
                    "type": "NET_TOTAL",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 2.92
                    }
                }
            ],
            "orderStatus": "CLOSED",
            "buyingCustomer": {
                "name": "Test Business",
                "email": "[email protected]"
            },
            "buyerGroup": {
                "name": "Department1"
            },
            "businessOrderInfo": null,
            "approverDetails": null
        }
    ],
    "nextPageToken": "123asda",
    "size": 1
}

Step 2. (Optional) Retrieve the next page of data

If the number of matching orders exceeds 100, the response will include a nextPageToken value. To get the next page of orders, make another getOrderReportsByPurchaseOrderNumber call with the same parameters and values as the last request. In addition, include the nextPageToken query parameter:

Type	Name	Description	Schema	Required
Query	`nextPageToken`	A page token returned in the response to your previous request when the number of results exceed the page size. Must be used with the same query parameters as the original request. Changing parameters will result in an error. To get the next page of results, include pageToken as a parameter. There are no more pages to return when the response returns no nextPageToken.	string	Yes

GET https://na.business-api.amazon.com/reports/2025-06-09/purchaseOrders/PoNumber1/orderReports?region=US&nextPageToken=123asda

import requests

url = "https://na.business-api.amazon.com/reports/2025-06-09/purchaseOrders/PoNumber1/orderReports?region=US&nextPageToken=123asda"

headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
}

response = requests.get(url, headers=headers)

print(response.text)

The response format will be identical to Step 1, containing the next page of data. Continue making requests with the nextPageToken until no token is returned in the response.

{
    "ordersReport": [
        {
            "orderMetadata": {
                "orderDate": "2024-11-08T21:29:44Z",
                "orderId": "114-0575598-4117065",
                "region": "US"
            },
            "purchaseOrderNumber": "PoNumber2",
            "charges": [
                {
                    "type": "SUBTOTAL",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 2.65
                    }
                },
                {
                    "type": "SHIPPING_AND_HANDLING",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 0.0
                    }
                },
                {
                    "type": "PROMOTION",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 0.0
                    }
                },
                {
                    "type": "TAX",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 0.27
                    }
                },
                {
                    "type": "NET_TOTAL",
                    "amount": {
                        "currencyCode": "USD",
                        "amount": 2.92
                    }
                }
            ],
            "orderStatus": "CLOSED",
            "buyingCustomer": {
                "name": "Test Business",
                "email": "[email protected]"
            },
            "buyerGroup": {
                "name": "Department2"
            },
            "businessOrderInfo": null,
            "approverDetails": null
        }
    ],
    "nextPageToken": null,
    "size": 1
}