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:
- 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 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
startDateandendDate. Otherwise, the call will fail.
| Type | Name | Description | Schema | Required |
|---|---|---|---|---|
| Query | startDate | The 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 |
| Query | endDate | The 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 |
| Query | includeLineItems | An option to get all line items associated with the order. If not included in the request, this value defaults to false. | boolean | No |
| Query | includeShipments | An option to get all shipments associated with the order. If not included in the request, this value defaults to false. | boolean | No |
| Query | includeCharges | An option to get all charges associated with the order. If not included in the request, this value defaults to false. | boolean | No |
| Query | nextPageToken | A 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 | No |
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:
| Name | Description | Schema |
|---|---|---|
orders | An array of orders within the given date range. | < Order > array |
nextPageToken | A 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 |
size | The 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:
| 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 (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 | Yes |
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.
Updated 4 months ago