Retrieving invoice details

Reconciliation API allows you to retrieve the invoice number associated with one or more order line items. For consolidated invoices, the API can also retrieve the invoice date and consolidation block for consolidated invoices. You can use this information to match Amazon Business transactions with their associated invoices, automating the reconciliation process.

📘

This guide explains how to retrieve invoice details in North American (NA) and European (EU) regions. If you are calling this API in the Japanese (JP) region, see Retrieving invoice details in JP region.

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 Business Purchase Reconciliation role. For more information, see Amazon Business API roles.
  3. Retrieve the order ID, order line item ID, and shipment ID associated with your desired transaction. One way to retrieve these details is to call the getTransactions operation. For more information, see Retrieving business transactions.

Retrieve invoice details

Call the getInvoiceDetailsByOrderLineItems operation. In the request, include the following fields:

NameDescriptionSchemaRequired
orderLineItemsList of order line items for the requested invoice details. The maximum number of order line items listed in each call is 25. For each line item, provide the order ID, order line item ID, and shipment ID in the request.< OrderLineItem > arrayYes

POST https://na.business-api.amazon.com/reconciliation/2021-01-08/invoices

{
    "orderLineItems": [
        {
            "orderId": "111-1087441-1234567",
            "orderLineItemId": "92258882544123",
            "shipmentId": "XWwjNjAbC"
        }
    ]
}
import requests

url = "https://na.business-api.amazon.com/reconciliation/2021-01-08/invoices"

payload = {
   "orderLineItems": [
        {
            "orderId": "111-1087441-1234567",
            "orderLineItemId": "92258882544123",
            "shipmentId": "XWwjNjAbC"
        }
    ]
}

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

response = requests.post(url, json=payload, headers=headers)

print(response.text)

A successful request returns an array of invoices that match the IDs provided in the request. The invoiceNumber and invoiceDate are returned for each orderLineItem.

The response includes the following details:

NameDescriptionSchemaRequired
invoiceDetailsByOrderLineItemsLists the invoices that includes order line item and invoice details.< InvoiceDetailsOfOrderLineItem > arrayYes

If you are also using Document API in the US region, you can use the invoiceNumber to programmatically retrieve your invoice documents. For more information, see Downloading invoices in NA.

{
    "invoiceDetailsByOrderLineItems": [
        {
            "orderLineItem": {
                "orderId": "111-1087441-1234567",
                "orderLineItemId": "92258882544123",
                "shipmentId": "XWwjNjAbC"
            },
            "invoiceDetails": [
                {
                    "invoiceNumber": "1677-HWGG-ABCD",
                    "invoiceDate": "2023-11-22T11:23:04.37Z"
                }
            ]
        }
    ]
}

EU and JP only: If the invoice is a consolidated invoice, the consolidated invoice number will be present in the consolidatedInvoiceDetails object.

{
    "invoiceDetailsByOrderLineItems": [
        {
            "orderLineItem": {
                "orderId": "111-2222222-3333333",
                "orderLineItemId": "1234567891234",
                "shipmentId": "A1b2CD34E"
            },
            "invoiceDetails": [
                {
                    "invoiceNumber": "DE4UPC2ABEY",
                    "invoiceDate": "2024-07-19T09:20:36.767Z",
                    "consolidatedInvoiceDetails": {
                        "invoiceNumber": "DE4UPC2ABEY"
                    }
                }
            ]
        }
    ]
}

You can use this consolidated invoice number to retrieve a consolidated invoice document using Document API. For more information, see Downloading invoices in EU and JP regions.

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.