Retrieving orders by date range

Reporting API allows you, as an Amazon Business developer, to retrieve orders that were created within a given date range. The API returns a paginated list of orders within the provided timeline, including each order’s quantity, subtotals, buying department, taxation, and net totals. Optionally, the API can also return the line items, shipments, and charges associated with each order. This data can be used to populate dashboards that help your customers analyze their Amazon Business spending, categorize their suppliers, and view their buying data.

Prerequisites

Before starting this tutorial, complete these steps:

  1. 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.
  2. Gain access to the Amazon Business Analytics role. For more information, see Amazon Business API roles.

Step 1. Retrieve orders by date range

Call the getOrdersByOrderDate operation. In the request, include the following query parameters:

🚧

There can be a maximum of 24 hours between the startDate and endDate. Otherwise, the call will fail.

TypeNameDescriptionSchemaRequired
QuerystartDateThe lower limit for the search range. This date represents the order date. This date is presented in yyyy-MM-dd'T'HH:mm:ss.SSS z, in which z represents the local time zone.string (date-time)Yes
QueryendDateThe upper limit for the search range. This date represents the order date. yyyy-MM-dd'T'HH:mm:ss.SSS z, in which z represents the local time zone.string (date-time)Yes
QueryincludeLineItemsAn option to get all line items associated with the order. If not included in the request, this value defaults to false.booleanNo
QueryincludeShipmentsAn option to get all shipments associated with the order. If not included in the request, this value defaults to false.booleanNo
QueryincludeChargesAn option to get all charges associated with the order. If not included in the request, this value defaults to false.booleanNo
QuerynextPageTokenA page token returned in the response to your previous request when the number of results exceed the page size (100). To get the next page of results, include nextPageToken as the only parameter. There are no more pages to return when the response returns no nextPageToken. This token needs to be encoded.stringNo

GET https://na.business-api.amazon.com/reports/2021-01-08/orders?startDate=2024-07-18T00%3A30%3A02Z&endDate=2024-07-18T00%3A38%3A02Z&includeLineItems=true&includeShipments=true&includeCharges=true
import requests

url = "https://na.business-api.amazon.com/reports/2021-01-08/orders?startDate=2024-07-18T00%3A30%3A02Z&endDate=2024-07-18T00%3A38%3A02Z&includeLineItems=true&includeShipments=true&includeCharges=true"

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 request returns the following details:

NameDescriptionSchema
ordersAn array of orders within the given date range.< Order > array
nextPageTokenA page token returned in the response to your previous request when the number of results exceed the page size (100). To get the next page of results, include nextPageToken as the only parameter. There are no more pages to return when the response returns no nextPageToken. This token needs to be encoded.string
sizeThe quantity of orders returned in the current response.integer

{
    "orders": [
        {
            "orderDate": "2024-07-17T19:07:12Z",
            "orderId": "113-6178736-2906618",
            "purchaseOrderNumber": "Billing address test",
            "orderQuantity": 0,
            "orderStatus": "CANCELLED",
            "lastOrderApproverName": null,
            "buyingCustomer": {
                "id": "",
                "name": "John Doe",
                "email": "[email protected]"
            },
            "buyerGroupName": "Public Group for Testing",
            "businessOrderInfo": {},
            "orderSubTotal": {
                "currencyCode": "USD",
                "amount": "61.49"
            },
            "orderShippingAndHandling": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderPromotion": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderTax": {
                "currencyCode": "USD",
                "amount": "5.07"
            },
            "orderNetTotal": {
                "currencyCode": "USD",
                "amount": "66.56"
            },
            "lineItems": [
                {
                    "productCategory": "Office Product",
                    "asin": "B0006BAHO2",
                    "title": "Office Depot® - Copy Paper - Quality Copy Paper 20 lb - Paper - 8-1/2\" x 11\" - Size 8-1/2\" x 11\" - White - 500 sh/rm - C",
                    "unspsc": "14111507",
                    "productCondition": "New",
                    "listedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "74.99"
                    },
                    "purchasedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "0"
                    },
                    "itemQuantity": 0,
                    "itemSubTotal": {
                        "currencyCode": "USD",
                        "amount": "61.49"
                    },
                    "itemShippingAndHandling": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "itemPromotion": null,
                    "itemTax": {
                        "currencyCode": "USD",
                        "amount": "5.07"
                    },
                    "itemNetTotal": {
                        "currencyCode": "USD",
                        "amount": "66.56"
                    },
                    "purchaseOrderLineItem": "externalID-LineLevel-1",
                    "taxExemptionApplied": false,
                    "taxExemptionType": null,
                    "taxExemptOptOut": false,
                    "discountProgram": "bp",
                    "discountType": null,
                    "discountAmount": null,
                    "discountRatio": null,
                    "seller": {
                        "sellerName": "Rita's Tape Media LLC DBA CompuPro Global",
                        "sellerPrimaryAddress": {
                            "addressLine1": "24285 Katy Freeway",
                            "addressLine2": "Ste. 300",
                            "city": "Katy",
                            "state": "TX",
                            "postalCode": "77494",
                            "countryCode": "US"
                        },
                        "sellerCity": "Katy",
                        "sellerState": "TX",
                        "sellerPostalCode": "77494"
                    },
                    "sellerCredentials": [
                        "Women-Owned Small Business",
                        "Registered Small Business",
                        "Women-Owned Business Enterprise",
                        "Economically Disadvantaged Women-Owned Small Business"
                    ],
                    "sellerCredentialDetails": [
                        {
                            "certificateType": "Women-Owned Business Enterprise",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "WBENC",
                                    "certificateExpirationDate": "2025-01-31T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Economically Disadvantaged Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Registered Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        }
                    ],
                    "brandCode": null,
                    "brandName": "Office Depot",
                    "manufacturerName": "Office Depot",
                    "transactionIds": [],
                    "carrierTrackingNumbers": []
                }
            ],
            "shipments": [],
            "charges": []
        },
        {
            "orderDate": "2024-07-17T19:27:42Z",
            "orderId": "113-6714347-8625829",
            "purchaseOrderNumber": "Billing address test",
            "orderQuantity": 0,
            "orderStatus": "CANCELLED",
            "lastOrderApproverName": null,
            "buyingCustomer": {
                "id": "",
                "name": "Jane Doe",
                "email": "[email protected]"
            },
            "buyerGroupName": "Public Group for Testing",
            "businessOrderInfo": {},
            "orderSubTotal": {
                "currencyCode": "USD",
                "amount": "61.49"
            },
            "orderShippingAndHandling": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderPromotion": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderTax": {
                "currencyCode": "USD",
                "amount": "5.07"
            },
            "orderNetTotal": {
                "currencyCode": "USD",
                "amount": "66.56"
            },
            "lineItems": [
                {
                    "productCategory": "Office Product",
                    "asin": "B0006BAHO2",
                    "title": "Office Depot® - Copy Paper - Quality Copy Paper 20 lb - Paper - 8-1/2\" x 11\" - Size 8-1/2\" x 11\" - White - 500 sh/rm - C",
                    "unspsc": "14111507",
                    "productCondition": "New",
                    "listedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "74.99"
                    },
                    "purchasedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "0"
                    },
                    "itemQuantity": 0,
                    "itemSubTotal": {
                        "currencyCode": "USD",
                        "amount": "61.49"
                    },
                    "itemShippingAndHandling": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "itemPromotion": null,
                    "itemTax": {
                        "currencyCode": "USD",
                        "amount": "5.07"
                    },
                    "itemNetTotal": {
                        "currencyCode": "USD",
                        "amount": "66.56"
                    },
                    "purchaseOrderLineItem": "externalID-LineLevel-1",
                    "taxExemptionApplied": false,
                    "taxExemptionType": null,
                    "taxExemptOptOut": false,
                    "discountProgram": "bp",
                    "discountType": null,
                    "discountAmount": null,
                    "discountRatio": null,
                    "seller": {
                        "sellerName": "Rita's Tape Media LLC DBA CompuPro Global",
                        "sellerPrimaryAddress": {
                            "addressLine1": "24285 Katy Freeway",
                            "addressLine2": "Ste. 300",
                            "city": "Katy",
                            "state": "TX",
                            "postalCode": "77494",
                            "countryCode": "US"
                        },
                        "sellerCity": "Katy",
                        "sellerState": "TX",
                        "sellerPostalCode": "77494"
                    },
                    "sellerCredentials": [
                        "Women-Owned Small Business",
                        "Registered Small Business",
                        "Women-Owned Business Enterprise",
                        "Economically Disadvantaged Women-Owned Small Business"
                    ],
                    "sellerCredentialDetails": [
                        {
                            "certificateType": "Women-Owned Business Enterprise",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "WBENC",
                                    "certificateExpirationDate": "2025-01-31T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Economically Disadvantaged Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Registered Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        }
                    ],
                    "brandCode": null,
                    "brandName": "Office Depot",
                    "manufacturerName": "Office Depot",
                    "transactionIds": [],
                    "carrierTrackingNumbers": []
                }
            ],
            "shipments": [],
            "charges": []
        }
    ],
    "nextPageToken": "token123",
    "size": 2
}

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

Reporting API returns a maximum of 100 orders in a single response. If the number of results exceeds this limit, the API response will include a nextPageToken value. This token can be used to retrieve the next page of orders within the provided date range.

To get the next page of results, make another call to getOrdersByOrderDate operation with nextPageToken as the only query parameter:

TypeNameDescriptionSchemaRequired
QuerynextPageTokenA page token returned in the response to your previous request when the number of results exceed the page size (100). To get the next page of results, include nextPageToken as the only parameter. There are no more pages to return when the response returns no nextPageToken. This token needs to be encoded.stringYes

GET  https://na.business-api.amazon.com/reports/2021-01-08/orders?nextPageToken=token123
import requests

url = "GET  https://na.business-api.amazon.com/reports/2021-01-08/orders?nextPageToken=token123"

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 request returns another page of orders matching the criteria in the request. If the number of orders in the response exceeds 100, another nextPageToken value is returned in the response. Continue passing the nextPageToken parameter on each call to iterate through all of the paginated results until a response no longer includes a nextPageToken value. At this point, you will have retrieved the full set of orders within the date range.

{
    "orders": [
        {
            "orderDate": "2024-07-17T19:07:12Z",
            "orderId": "113-6178736-2906619",
            "purchaseOrderNumber": "Billing address test",
            "orderQuantity": 0,
            "orderStatus": "CANCELLED",
            "lastOrderApproverName": null,
            "buyingCustomer": {
                "id": "",
                "name": "John Doe",
                "email": "[email protected]"
            },
            "buyerGroupName": "Public Group for Testing",
            "businessOrderInfo": {},
            "orderSubTotal": {
                "currencyCode": "USD",
                "amount": "61.49"
            },
            "orderShippingAndHandling": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderPromotion": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderTax": {
                "currencyCode": "USD",
                "amount": "5.07"
            },
            "orderNetTotal": {
                "currencyCode": "USD",
                "amount": "66.56"
            },
            "lineItems": [
                {
                    "productCategory": "Office Product",
                    "asin": "B0006BAHO2",
                    "title": "Office Depot® - Copy Paper - Quality Copy Paper 20 lb - Paper - 8-1/2\" x 11\" - Size 8-1/2\" x 11\" - White - 500 sh/rm - C",
                    "unspsc": "14111507",
                    "productCondition": "New",
                    "listedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "74.99"
                    },
                    "purchasedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "0"
                    },
                    "itemQuantity": 0,
                    "itemSubTotal": {
                        "currencyCode": "USD",
                        "amount": "61.49"
                    },
                    "itemShippingAndHandling": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "itemPromotion": null,
                    "itemTax": {
                        "currencyCode": "USD",
                        "amount": "5.07"
                    },
                    "itemNetTotal": {
                        "currencyCode": "USD",
                        "amount": "66.56"
                    },
                    "purchaseOrderLineItem": "externalID-LineLevel-1",
                    "taxExemptionApplied": false,
                    "taxExemptionType": null,
                    "taxExemptOptOut": false,
                    "discountProgram": "bp",
                    "discountType": null,
                    "discountAmount": null,
                    "discountRatio": null,
                    "seller": {
                        "sellerName": "Rita's Tape Media LLC DBA CompuPro Global",
                        "sellerPrimaryAddress": {
                            "addressLine1": "24285 Katy Freeway",
                            "addressLine2": "Ste. 300",
                            "city": "Katy",
                            "state": "TX",
                            "postalCode": "77494",
                            "countryCode": "US"
                        },
                        "sellerCity": "Katy",
                        "sellerState": "TX",
                        "sellerPostalCode": "77494"
                    },
                    "sellerCredentials": [
                        "Women-Owned Small Business",
                        "Registered Small Business",
                        "Women-Owned Business Enterprise",
                        "Economically Disadvantaged Women-Owned Small Business"
                    ],
                    "sellerCredentialDetails": [
                        {
                            "certificateType": "Women-Owned Business Enterprise",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "WBENC",
                                    "certificateExpirationDate": "2025-01-31T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Economically Disadvantaged Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Registered Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        }
                    ],
                    "brandCode": null,
                    "brandName": "Office Depot",
                    "manufacturerName": "Office Depot",
                    "transactionIds": [],
                    "carrierTrackingNumbers": []
                }
            ],
            "shipments": [],
            "charges": []
        },
        {
            "orderDate": "2024-07-17T19:27:42Z",
            "orderId": "113-6714347-1234567",
            "purchaseOrderNumber": "Billing address test",
            "orderQuantity": 0,
            "orderStatus": "CANCELLED",
            "lastOrderApproverName": null,
            "buyingCustomer": {
                "id": "",
                "name": "Jane Doe",
                "email": "[email protected]"
            },
            "buyerGroupName": "Public Group for Testing",
            "businessOrderInfo": {},
            "orderSubTotal": {
                "currencyCode": "USD",
                "amount": "61.49"
            },
            "orderShippingAndHandling": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderPromotion": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderTax": {
                "currencyCode": "USD",
                "amount": "5.07"
            },
            "orderNetTotal": {
                "currencyCode": "USD",
                "amount": "66.56"
            },
            "lineItems": [
                {
                    "productCategory": "Office Product",
                    "asin": "B0006BAHO2",
                    "title": "Office Depot® - Copy Paper - Quality Copy Paper 20 lb - Paper - 8-1/2\" x 11\" - Size 8-1/2\" x 11\" - White - 500 sh/rm - C",
                    "unspsc": "14111507",
                    "productCondition": "New",
                    "listedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "74.99"
                    },
                    "purchasedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "0"
                    },
                    "itemQuantity": 0,
                    "itemSubTotal": {
                        "currencyCode": "USD",
                        "amount": "61.49"
                    },
                    "itemShippingAndHandling": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "itemPromotion": null,
                    "itemTax": {
                        "currencyCode": "USD",
                        "amount": "5.07"
                    },
                    "itemNetTotal": {
                        "currencyCode": "USD",
                        "amount": "66.56"
                    },
                    "purchaseOrderLineItem": "externalID-LineLevel-1",
                    "taxExemptionApplied": false,
                    "taxExemptionType": null,
                    "taxExemptOptOut": false,
                    "discountProgram": "bp",
                    "discountType": null,
                    "discountAmount": null,
                    "discountRatio": null,
                    "seller": {
                        "sellerName": "Rita's Tape Media LLC DBA CompuPro Global",
                        "sellerPrimaryAddress": {
                            "addressLine1": "24285 Katy Freeway",
                            "addressLine2": "Ste. 300",
                            "city": "Katy",
                            "state": "TX",
                            "postalCode": "77494",
                            "countryCode": "US"
                        },
                        "sellerCity": "Katy",
                        "sellerState": "TX",
                        "sellerPostalCode": "77494"
                    },
                    "sellerCredentials": [
                        "Women-Owned Small Business",
                        "Registered Small Business",
                        "Women-Owned Business Enterprise",
                        "Economically Disadvantaged Women-Owned Small Business"
                    ],
                    "sellerCredentialDetails": [
                        {
                            "certificateType": "Women-Owned Business Enterprise",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "WBENC",
                                    "certificateExpirationDate": "2025-01-31T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Economically Disadvantaged Women-Owned Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        },
                        {
                            "certificateType": "Registered Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-01-25T00:00:00Z"
                                }
                            ]
                        }
                    ],
                    "brandCode": null,
                    "brandName": "Office Depot",
                    "manufacturerName": "Office Depot",
                    "transactionIds": [],
                    "carrierTrackingNumbers": []
                }
            ],
            "shipments": [],
            "charges": []
        }
    ],
    "nextPageToken": "",
    "size": 2
}

Error handling

If your request is not successful, the API returns an errors object that provides information about what went wrong. For more information, see Error responses and schemas.