How to download invoices

This tutorial details the steps on how to download invoices for a transaction returned from Reconciliation API.

🚧
If you're querying reports in Amazon Business US, complete the prerequisites and the steps in Step 0. Retrieve invoice details, Step 1. Request a report, Step 2. Confirm completion of the report process, and Step 3. Retrieve the report.
If you're querying reports in EU or FE region, complete the prerequisites, Step1. Request a report, Step 2. Confirm completion of the report process, and Step 3. Retrieve the report.

Prerequisites

To successfully complete this tutorial, do these steps:

Connect with Amazon Business for authentication and authorization. Refer to Onboarding Step 3: Authorize your Amazon Business API apps.
Call Reconciliation API to get the orderId, orderLineItemId, and shipmentId in the transactionLineItems.

Here's a sample response after calling the Reconciliation API.

{
    "transactions": [
        {
            "transactionDate": "",
            "feedDate": "",
            "transactionType": "CHARGE",
            "transactionId": "",
            "legalEntityName": "",
            "amount": {
                "currencyCode": "",
                "amount": ""
            },
            "paymentInstrumentType": "",
            "paymentInstrumentLast4Digits": "",
            "buyer": {
                "id": "",
                "name": "",
                "email": ""
            },
            "payer": {
                "id": "",
                "name": "",
                "email": ""
            },
            "associatedTransactionDetails": [],
            "transactionLineItems": [
                {
                    "refundReason": ,
                    "totalAmount": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "principalAmount": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "shippingCharge": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": null,
                    "tax": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "unitPrice": null,
                    "orderId": "8888888888",
                    "unspsc": "",
                    "orderLineItemId": "000-000-0000000000000",
                    "purchaseOrderNumber": "",
                    "purchaseOrderLineItemId": null,
                    "asin": "",
                    "productTitle": "",
                    "itemQuantity": ,
                    "shipmentId": "EfsA23Vs",
                    "shipmentDate": "",
                    "merchantLegalName": "",
                    "budgetId": "",
                    "businessOrderInfo": null
                }
            ]
        },
        {
            "transactionDate": "",
            "feedDate": "",
            "transactionType": "",
            "transactionId": "",
            "legalEntityName": "",
            "amount": {
                "currencyCode": "",
                "amount": ""
            },
            "paymentInstrumentType": "",
            "paymentInstrumentLast4Digits": "",
            "buyer": {
                "id": "",
                "name": "",
                "email": ""
            },
            "payer": {
                "id": "",
                "name": "",
                "email": ""
            },
            "associatedTransactionDetails": [],
            "transactionLineItems": [
                {
                    "refundReason": null,
                    "totalAmount": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "principalAmount": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "shippingCharge": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": null,
                    "tax": {
                        "currencyCode": "",
                        "amount": ""
                    },
                    "unitPrice": null,
                    "orderId": "9999999999",
                    "unspsc": "",
                    "orderLineItemId": "111-111-1111111111111",
                    "purchaseOrderNumber": "",
                    "purchaseOrderLineItemId": null,
                    "asin": "",
                    "productTitle": "",
                    "itemQuantity": ,
                    "shipmentId": "DfsA23Vs",
                    "shipmentDate": "",
                    "merchantLegalName": "",
                    "budgetId": "",
                    "businessOrderInfo": null
                }
            ]
        }
    ],
    "nextPageToken": null
}

In the sample response, the transactionLineItems have two objects: lineItem1 and lineItem2. Each lineItem has orderId, orderLineItemId, and shipmentId parameters. Save the data you see in these parameters.

Sample data:

lineItem1
orderId: "8888888888"
orderLineItemId: "000-000-0000000000000"
shipmentId: "EfsA23Vs"

lineitem2
orderId: "9999999999"
orderLineItemId: "111-111-1111111111111",
shipmentId: "DfsA23Vs"

In EU and JP regions, you can call the getInvoiceDetailsByOrderLineItems operation by passing the OrderLineItem parameters in the request body to retrieve additional invoice details, including the invoiceNumber for a consolidated invoice:

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

Step 0. Retrieve invoice details

Request InvoiceNumbers associated with the above lineItems.
Call the getInvoiceDetailsByOrderLineItems operation by passing the OrderLineItem parameters in the request body.

POST https://na.business-api.amazon.com/reconciliation/2021-01-08/invoices
{
    "orderLineItems": [
        {
            "orderId": REPLACE_WITH_ORDER_ID,
            "orderLineItemId": REPLACE_WITH_ORDER_LINE_ITEM_ID,
            "shipmentId": REPLACE_WITH_SHIPMENT_ID
        }
    ]
}

Provide data in the orderId, orderLineItemId, and shipmentId.

Example:
orderId: "9999999999"
orderLineItemId: "111-111-1111111111111",
shipmentId: "DfsA23Vs"

A successful response includes the parameters in InvoiceDetail.

{
  "invoiceDetailsByOrderLineItems": [
    {
      "orderLineItem": {
        "orderId": "9999999999",
        "orderLineItemId": "111-111-1111111111111",
        "shipmentId": "DfsA23Vs"
      },
      "invoiceDetails": [
        {
          "invoiceNumber": "1111-2222-3333",
          "invoiceDate": "2021-03-24T00:52:10.618Z"
        }
      ]
    }
  ]
}

Step 1. Request a report

Amazon Business US only

📘
In US, Document API supports the download of Pay by Invoice (PBI) and credit memo documents. You can specify Credits in the documentType field to return only the credit memo linked to the invoice ID, or include the invoice ID in the request to receive both the credit memo and invoice documents.

Request a report by specifying the reportOptions, reportType, marketplaceIds, invoiceId, invoiceType, and any optional parameters.
Call the createReport operation by passing these parameters in the request body.

Name	Description	Type	Required
`reportOptions`	Additional information passed to reports. This varies by report type.	`ReportOptions`	Yes
`reportType`	Supported value is GET_AB_INVOICE_PDF.	string	Yes
`marketplaceIds`	A list of Amazon Business marketplace identifiers. The report contains data for all of the specified Amazon Business marketplace, unless the report type indicates otherwise.	< string > array	Yes

Provide the following fields in the reportOptions object to identify the type of document to download:

Name	Description	Type	Required
`invoiceId`	The unique invoice identifier. Based on this identifier, the correct invoice or credit memo document will be vended.	string	Yes
`invoiceType`	[Note: `invoiceType` will be deprecated. To download invoice documents, use `documentType` instead.] Type of invoice to download. Supported value is `PBI_INVOICE`.	string	No
`documentType`	The type of document to download. Supported values include `Invoice` or `Credits`.	string	No

📘
Either invoiceType or documentType can be included in reportOptions. If neither field is included, both invoice and credit memo documents are downloaded. If both fields are included, the request is invalid.

Provide the invoiceID. This is the invoiceNumber value shown in Step 0 sample response. As an example, your invoiceID here will be 1111-2222-3333.

{ 
    "reportOptions": 
    { 
        "invoiceId":invoiceId, 
        "documentType": "Credits" 
    }, 
    "reportType": "GET_AB_INVOICE_PDF", 
    "marketplaceIds": ["ATVPDKIKX0DER"] 
}

A successful response includes:

Name	Description	Type	Required
`reportId`	The identifier for the report. This identifier is unique only in combination with Amazon Business customer.	string	Yes

{
  "reportId": "ID323"
}

🚧
If you're querying reports in Amazon Business US, proceed to Step 2. Confirm completion of the report process.

FE or EU region only

📘
In EU, Document API supports the download of PDF invoices where Amazon Business is the supplier of record (Invoice by Amazon) or if a third-party vendor is part of Amazon Business VAT Calculation Services (VCS) program. Document API now supports download of credit memo documents for EU and JP. For EU, credit memo documents supported are IBA, AB Retail, VCS, and VCS-lite credit memos. In the future, Document API will support download of Invoices and credit memos for Invoice Document Upload (IDU) and Seller Tax Exempted Program (STEP) transactions.
Document API also supports the download of consolidated invoices. Depending on the customer’s Amazon Business account settings, invoices can support purchase consolidation (one invoice including all line items in a purchase) and periodic consolidation (one invoice including all purchases shipped in a given time period). For more information, see Consolidated invoices.

Call the createReport operation by passing these parameters in the request body.

Name	Description	Type	Required
`reportOptions`	Additional information passed to reports. This varies by report type.	`ReportOptions`	Yes
`reportType`	Supported value is GET_AB_INVOICE_PDF.	string	Yes
`marketplaceIds`	A list of Amazon Business marketplace identifiers. The report contains data for all of the specified Amazon Business marketplace, unless the report type indicates otherwise.	< string > array	Yes

The required fields to include in the reportOptions object vary depending on the use case:

To retrieve a consolidated invoice, get the invoiceNumber from the consolidatedInvoiceDetails object of the Reconciliation API response and call the createReport operation with the following fields in the reportOptions object:

Name	Description	Type	Required
`invoiceId`	The unique invoice identifier.	string	Yes
`documentType`	The type of document to download. Supported value for this use case is `Invoice`.	string	Yes

📘
If the invoiceNumber returns Pending, poll the API until an invoice number is available. Once the invoice number is available, call the createReport operation.

To retrieve a shipment-based invoice or credit memo document, call the createReport operation with orderId, orderLineItemId, shipmentId, and documentType in the request.

Name	Description	Type	Required
`orderId`	The unique order identifier.	string	Yes
`orderLineItemId`	The unique order line item identifier.	string	Yes
`shipmentId`	The unique shipment identifier.	string	No
`documentType`	The type of document to download. Supported values for this use case include `Invoice` or `Credits`. If this field is not included in the request, both invoice and credit memo documents will be downloaded.	string	No

Here is a sample request to download a consolidated invoice:

{ 
    "reportOptions": 
    { 
        "invoiceId":DE412022ABEY, 
        "documentType": "Invoice" 
    }, 
    "reportType": "GET_AB_INVOICE_PDF", 
    "marketplaceIds": ["A1PA6795UKMFR9"] 
}

Here is a sample request to download a shipment-based invoice:

{
   "reportType": "GET_AB_INVOICE_PDF",
   "marketplaceIds": [
     "A1PA6795UKMFR9"
   ],
   "reportOptions": {
     "orderId": "203-9277085-5441169",
     "orderLineItemId": "20710282414442",
     "shipmentId": "D6jrvDy6t",
     "documentType": "Invoice"
   }
 }

A successful response includes:

Name	Description	Type	Required
`reportId`	The identifier for the report. This identifier is unique only in combination with Amazon Business customer.	string	Yes

{
   "reportId": "ID323" 
}

Step 2. Confirm completion of the report process

After you call the createReport operation, Amazon Business receives the request and processes the report.

To confirm completion of the report process, call the getReport operation periodically.

📘
The getReport operation only serves information for on-demand or scheduled report requests that were created within the last 30 days.

If the report process is complete, proceed to Step 3. Retrieve the report.

If the report process isn't complete, resend the request by passing the reportId value.

Name	Description	Type	Required
`reportId`	The identifier for the report. This identifier is unique only in combination with Amazon Business customer.	string	Yes

Continue to call the getReport operation until the value in the response indicates that report process has ended. The report process has ended if the processingStatus indicates CANCELLED, DONE, or FATAL. The report process hasn't ended if the values indicate IN_PROGRESS or IN_QUEUE.

GET https://eu.business-api.amazon.com/reports/2021-09-30/reports/ID323

A successful response includes:

Name	Description	Schema
Report	The payload for the `getReport` operation.	Report

{
  "reportId": "ID323",
  "reportType": "GET_AB_INVOICE_PDF",
  "dataStartTime": "2019-12-11T13:47:20.677Z",
  "dataEndTime": "2019-12-12T13:47:20.677Z",
  "createdTime": "2019-12-10T13:47:20.677Z",
  "processingStatus": "DONE",
  "processingStartTime": "2019-12-10T13:47:20.677Z",
  "marketplaceIds": [
    "A1PA6795UKMFR9"
  ],
  "processingEndTime": "2019-12-12T13:47:20.677Z",
  "reportOptions": {
    "orderId": "503-5002996-6583839",
    "orderLineItemId": "9253990283445",
    "shipmentId": "Drs80HLSQ",
    "documentType": "Invoice"
  }
  "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760"
}

📘
If a report is available, the response will include a reportDocumentId.

Step 3. Retrieve the report

Call the getReportDocument operation by passing this path parameter.

Name	Description	Type	Required
`reportDocumentId`	The identifier for the report document.	string	Yes

📘
The report includes a presigned URL. If the content is compressed, the report will include the compression algorithm.

GET https://eu.business-api.amazon.com/reports/2021-09-30/documents/DOC-b8b0-4226-b4b9-0ee058ea5760

Save the url and compressionAlgorithm (optional). You'll need these to download a report.

A successful response includes:

Name	Description	Type
`reportDocumentId`	The identifier for the report document. This identifier is unique only in combination with Amazon Business customer.	string
`url`	A presigned URL for the report document. This URL expires after five minutes.	string
`compressionAlgorithm`	If present, the report document contents have been compressed with the provided algorithm.	string

{
  "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
  "compressionAlgorithm": "GZIP",
  "url": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8"
}

🚧
Reports contain sensitive information. Don't save unencrypted report on a disk, even temporarily.

Download the report using the url and compressionAlgorithm (optional) values.

📘
The downloaded file is compressed twice: first with zip, then with gzip. To view the PDF, decompress the file in reverse order: first use gzip to decompress the file, then unzip the resulting file to access the PDF.

This sample code demonstrates how to download a plain text report document. You can use this example for other programming languages or types of documents, such as XML, CSV, and TSV.

// DownloadExample.java
import java.io.BufferedReader;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import java.util.zip.GZIPInputStream;

import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.ResponseBody;

/**
 * Example that downloads a document.
 */
public class DownloadExample {

  public static void main(String args[]) {
    String url = "<URL from the getFeedDocument/getReportDocument response>";
    String compressionAlgorithm = "<compressionAlgorithm from the getFeedDocument/getReportDocument response>";

    DownloadExample obj = new DownloadExample();
    try {
      obj.download(url, compressionAlgorithm);
    } catch (IOException e) {
      //Handle exception here.
    } catch (IllegalArgumentException e) {
      //Handle exception here.
    }
  }

  /**
   * Download and optionally decompress the document retrieved from the given url.
   *
   * @param url                  the url pointing to a document
   * @param compressionAlgorithm the compressionAlgorithm used for the document
   * @throws IOException              when there is an error reading the response
   * @throws IllegalArgumentException when the charset is missing
   */
  public void download(String url, String compressionAlgorithm) throws IOException, IllegalArgumentException {
    OkHttpClient httpclient = new OkHttpClient();
    Request request = new Request.Builder()
      .url(url)
      .get()
      .build();

    Response response = httpclient.newCall(request).execute();
    if (!response.isSuccessful()) {
      System.out.println(
        String.format("Call to download content was unsuccessful with response code: %d and message: %s",
          response.code(), response.message()));
      return;
    }

    try (ResponseBody responseBody = response.body()) {
      MediaType mediaType = MediaType.parse(response.header("Content-Type"));
      Charset charset = mediaType.charset();
      if (charset == null) {
        throw new IllegalArgumentException(String.format(
          "Could not parse character set from '%s'", mediaType.toString()));
      }

      Closeable closeThis = null;
      try {
        InputStream inputStream = responseBody.byteStream();
        closeThis = inputStream;

        if ("GZIP".equals(compressionAlgorithm)) {
          inputStream = new GZIPInputStream(inputStream);
          closeThis = inputStream;
        }

        // This example assumes that the download content has a charset in the content-type header, e.g.
        // text/plain; charset=UTF-8
        if ("text".equals(mediaType.type()) && "plain".equals(mediaType.subtype())) {
          InputStreamReader inputStreamReader = new InputStreamReader(inputStream, charset);
          closeThis = inputStreamReader;

          BufferedReader reader = new BufferedReader(inputStreamReader);
          closeThis = reader;

          String line;
          do {
            line = reader.readLine();
            // Process line by line.
          } while (line != null);
        } else {
          //Handle content with binary data/other media types here.
        }
      } finally {
        if (closeThis != null) {
          closeThis.close();
        }
      }
    }
  }
}

📘
Poll the getReportId every 15 seconds to check the status of the report request.

Frequently asked questions

When does a transaction appears in the GET endpoint?
The transaction appears in the GET endpoint once the transaction event takes place on Amazon Business for a given order.
When is the invoice document available for download?
The invoice document is available for download once the shipment event takes place for a given order.