Retrieving an order by order ID

Reporting API allows you, as an Amazon Business developer, to retrieve an order by its unique Amazon order ID. The API returns detailed information about the order, including its quantity, subtotals, buying department, taxation, and net totals. Optionally, the API can also return the line items, shipments, and charges associated with the order. Your customers can use this data to generate insights about specific orders, supporting their spend reporting or analytics operations.

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.
Retrieve an Amazon order ID. You can find this ID in the order confirmation email after completing an Amazon Business order.

Retrieve an order by ID

Call the getOrdersByOrderId operation. In the request, include the following parameters:

Type	Name	Description	Schema	Required
Path	`orderId`	A unique Amazon-generated identifier for the order.	string	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

GET  https://na.business-api.amazon.com/reports/2021-01-08/orders/{orderId}?includeCharges=true&includeShipments=true&includeLineItems=true

import requests

url = "https://na.business-api.amazon.com/reports/2021-01-08/orders/{orderId}?includeCharges=true&includeShipments=true&includeLineItems=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 order matching the order ID. The response body includes the following fields:

Name	Description	Schema
`orders`	An array of orders matching the order ID.	< Order > array
`size`	The quantity of orders returned in the current response.	integer

{
    "orders": [
        {
            "orderDate": "2024-07-16T18:38:02Z",
            "orderId": "112-1234567-1234567",
            "purchaseOrderNumber": null,
            "orderQuantity": 0,
            "orderStatus": "CANCELLED",
            "lastOrderApproverName": null,
            "buyingCustomer": {
                "id": "",
                "name": "Jane Doe",
                "email": "[email protected]"
            },
            "buyerGroupName": "Example Department",
            "businessOrderInfo": {},
            "orderSubTotal": {
                "currencyCode": "USD",
                "amount": "70.91"
            },
            "orderShippingAndHandling": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderPromotion": {
                "currencyCode": "USD",
                "amount": "0.0"
            },
            "orderTax": {
                "currencyCode": "USD",
                "amount": "5.85"
            },
            "orderNetTotal": {
                "currencyCode": "USD",
                "amount": "76.76"
            },
            "lineItems": [
                {
                    "productCategory": "Office Product",
                    "asin": "B072FVQNWM",
                    "title": "Hammermill Printer Paper, 20 Lb Copy Paper, 8.5 x 11 - 8 Ream (4,000 Sheets) - 92 Bright, Made in the USA",
                    "unspsc": "14111507",
                    "productCondition": "New",
                    "listedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "55.99"
                    },
                    "purchasedPricePerUnit": {
                        "currencyCode": "USD",
                        "amount": "0"
                    },
                    "itemQuantity": 0,
                    "itemSubTotal": {
                        "currencyCode": "USD",
                        "amount": "70.91"
                    },
                    "itemShippingAndHandling": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "itemPromotion": null,
                    "itemTax": {
                        "currencyCode": "USD",
                        "amount": "5.85"
                    },
                    "itemNetTotal": {
                        "currencyCode": "USD",
                        "amount": "76.76"
                    },
                    "purchaseOrderLineItem": null,
                    "taxExemptionApplied": false,
                    "taxExemptionType": null,
                    "taxExemptOptOut": false,
                    "discountProgram": "bp",
                    "discountType": null,
                    "discountAmount": null,
                    "discountRatio": null,
                    "seller": {
                        "sellerName": "AnyCompany",
                        "sellerPrimaryAddress": {
                            "addressLine1": "123 Any Street",
                            "addressLine2": null,
                            "city": "Any Town",
                            "state": "WA",
                            "postalCode": "12345-1234",
                            "countryCode": "US"
                        },
                        "sellerCity": "Any Town",
                        "sellerState": "WA",
                        "sellerPostalCode": "12345"
                    },
                    "sellerCredentials": [
                        "Registered Small Business"
                    ],
                    "sellerCredentialDetails": [
                        {
                            "certificateType": "Registered Small Business",
                            "certifyingAgenciesDetails": [
                                {
                                    "certifyingAgencyName": "SAM",
                                    "certificateExpirationDate": "2025-03-25T00:00:00Z"
                                }
                            ]
                        }
                    ],
                    "brandCode": "HAMNF",
                    "brandName": "Hammermill",
                    "manufacturerName": "Sylvamo",
                    "transactionIds": [],
                    "carrierTrackingNumbers": []
                }
            ],
            "shipments": [],
            "charges": []
        }
    ],
    "size": 1
}

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.