Retrieving business transactions

Reconciliation API allows you to retrieve business transaction details within a date range. The API returns a paginated list of business transactions within the provided timeline, including details such as each transaction’s type, ID, payment method, purchase amount, tax rates, and line items. This data can be imported into your accounting system to simplify the reconciliation process.

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 Business Purchase Reconciliation role. For more information, see Amazon Business API roles.

Step 1. Retrieve business transactions

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

Type	Name	Description	Schema	Required
Query	`feedStartDate`	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	`feedEndDate`	The upper 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	`nextPageToken`	A page token that is returned when the results of the call exceed the page size. To get another page of results, call the operation again, passing in this value with the `nextPageToken` parameter.	string	No

GET https://na.business-api.amazon.com/reconciliation/2021-01-08/transactions?feedStartDate=2023-01-01T00:00:00Z&feedEndDate=2024-04-24T00:00:00Z

import requests

url = "https://na.business-api.amazon.com/reconciliation/2021-01-08/transactions?feedStartDate=2023-01-01T00:00:00Z&feedEndDate=2024-04-24T00:00:00Z"

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	Required
`transactions`	A list of transactions with feed dates that fall within the specified date range.	< Transaction > array	Yes
`nextPageToken`	A page token that is returned when the results of the call exceed the page size. To get another page of results, call the operation again, passing in this value with the nextPageToken parameter.	string	Ye

{
    "transactions": [
        {
            "marketplaceId": "ATVPDKIKX0DER",
            "transactionDate": "2024-01-17T17:49:40.115Z",
            "feedDate": "2024-01-17T18:19:47.351Z",
            "transactionType": "CHARGE",
            "transactionId": "3Q9IwkUp5KALWzoHgABc",
            "shipTaxRate": "0.00",
            "giftWrapTaxRate": "0.00",
            "legalEntityName": "AnyCompany",
            "purchasingCustomerGroupName": "AnyDepartment",
            "amount": {
                "currencyCode": "USD",
                "amount": "35.00"
            },
            "paymentInstrumentType": "MasterCard",
            "paymentInstrumentLast4Digits": "5791",
            "buyer": {
                "id": "amzn1.account.5TJ6RPJSRQV3XDJQSMDHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ7L76XFORRXON32VJZTAFMLQH5KFVALBUBQUKHM65TLKEYGFEYABC",
                "name": "John Doe",
                "email": "[email protected]"
            },
            "payer": {
                "id": "amzn1.account.YVOAUID4U6IT2TQLN6THEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ2ZFRMW26UBVMEHEZPXU7JV7S6WGJDD2I4TMJFB6YELXZRYLO7123",
                "name": "Example Corp",
                "email": "[email protected]"
            },
            "associatedTransactionDetails": [],
            "transactionLineItems": [
                {
                    "refundReason": null,
                    "totalAmount": {
                        "currencyCode": "USD",
                        "amount": "20.0"
                    },
                    "principalAmount": {
                        "currencyCode": "USD",
                        "amount": "20.0"
                    },
                    "shippingCharge": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": null,
                    "tax": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "unitPrice": {
                        "currencyCode": "USD",
                        "amount": "20.00"
                    },
                    "taxRate": "0.0",
                    "orderId": "111-1087441-5335454",
                    "unspsc": "14111803",
                    "orderLineItemId": "92258882544121",
                    "purchaseOrderNumber": "NCPROD00000006",
                    "purchaseOrderLineItemId": "2",
                    "asin": "B09ZJ41RCR",
                    "productTitle": "Amazon.com Gift Card for any amount in a Patriotic Water Color Premium Mini Envelope",
                    "itemQuantity": 1,
                    "shipmentId": "XWwjNjjDq",
                    "shipmentDate": "2024-01-17T17:13:34Z",
                    "merchantLegalName": "Amazon.com Services, Inc",
                    "budgetId": null,
                    "businessOrderInfo": null
                },
                {
                    "refundReason": null,
                    "totalAmount": {
                        "currencyCode": "USD",
                        "amount": "15.0"
                    },
                    "principalAmount": {
                        "currencyCode": "USD",
                        "amount": "15.0"
                    },
                    "shippingCharge": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": null,
                    "tax": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "unitPrice": {
                        "currencyCode": "USD",
                        "amount": "15.00"
                    },
                    "taxRate": "0.0",
                    "orderId": "111-1087441-5335454",
                    "unspsc": "14111803",
                    "orderLineItemId": "92254526924801",
                    "purchaseOrderNumber": "NCPROD00000006",
                    "purchaseOrderLineItemId": "1",
                    "asin": "B077T9WSSN",
                    "productTitle": "Amazon.com Gift Card in a Mini Envelope (Navy and Gold)",
                    "itemQuantity": 1,
                    "shipmentId": "XWwjNjjDq",
                    "shipmentDate": "2024-01-17T17:13:34Z",
                    "merchantLegalName": "Amazon.com Services, Inc",
                    "budgetId": null,
                    "businessOrderInfo": null
                }
            ]
        },
        {
            "marketplaceId": "ATVPDKIKX0DER",
            "transactionDate": "2023-02-15T01:12:46Z",
            "feedDate": "2023-02-15T01:43:22.562Z",
            "transactionType": "CHARGE",
            "transactionId": "2pQhc4tpJbBydGkURsZl",
            "shipTaxRate": "0.0825",
            "giftWrapTaxRate": "0.00",
            "legalEntityName": "AnyCompany",
            "purchasingCustomerGroupName": "AnyOrganization",
            "amount": {
                "currencyCode": "USD",
                "amount": "31.38"
            },
            "paymentInstrumentType": "Visa",
            "paymentInstrumentLast4Digits": "5316",
            "buyer": {
                "id": "amzn1.account.5TJ6RPJSRQV3XDJQSMDHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ7L76XFORRXON32VJZTAFMLQH5KFVALBUBQUKHM65TLKEYGFEYYPY",
                "name": "Jane Doe",
                "email": "[email protected]"
            },
            "payer": {
                "id": "amzn1.account.5TJ6RPJSRQV3XDJQSMDHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ7L76XFORRXON32VJZTAFMLQH5KFVALBUBQUKHM65TLKEYGFEYYPY",
                "name": "Jane Doe",
                "email": "[email protected]"
            },
            "associatedTransactionDetails": [],
            "transactionLineItems": [
                {
                    "refundReason": null,
                    "totalAmount": {
                        "currencyCode": "USD",
                        "amount": "31.38"
                    },
                    "principalAmount": {
                        "currencyCode": "USD",
                        "amount": "28.99"
                    },
                    "shippingCharge": {
                        "currencyCode": "USD",
                        "amount": "7.42"
                    },
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": {
                        "currencyCode": "USD",
                        "amount": "-7.42"
                    },
                    "tax": {
                        "currencyCode": "USD",
                        "amount": "2.39"
                    },
                    "unitPrice": {
                        "currencyCode": "USD",
                        "amount": "28.99"
                    },
                    "taxRate": "0.0825",
                    "orderId": "112-1585970-3601808",
                    "unspsc": "60141000",
                    "orderLineItemId": "73523523601641",
                    "purchaseOrderNumber": "NCDO00001",
                    "purchaseOrderLineItemId": null,
                    "asin": "B07GBNQJ3N",
                    "productTitle": "Happy 13th Birthday Decorations For Girls (104 Pk) 13 Balloon Numbers, 13th Birthday Banner, 13th Birthday Card, 13 Sash, 13th Birthday Plates, Teen G",
                    "itemQuantity": 1,
                    "shipmentId": "MtTR2HDtm",
                    "shipmentDate": "2023-02-14T23:50:19Z",
                    "merchantLegalName": "Paris Products Co. LLC",
                    "budgetId": null,
                    "businessOrderInfo": null
                }
            ]
        }
    ],
    "nextPageToken": null
}

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

If the number of matching transactions exceeds the Reconciliation API page size limit, the response will include a nextPageToken value. To get the next page of transactions, make another getTransactions call with the same parameters and values as the last request. In addition, include the nextPageToken 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 additional 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/reconciliation/2021-01-08/transactions?feedStartDate=2023-01-01T00:00:00Z&feedEndDate=2024-04-24T00:00:00Z?nextPageToken=token123

import requests

url = "GET https://na.business-api.amazon.com/reconciliation/2021-01-08/transactions?feedStartDate=2023-01-01T00:00:00Z&feedEndDate=2024-04-24T00:00:00Z?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 the page size limit, 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 transactions within the date range.

{
    "transactions": [
        {
            "marketplaceId": "ATVPDKIKX0DER",
            "transactionDate": "2023-02-14T02:58:49Z",
            "feedDate": "2023-02-14T03:29:24.999Z",
            "transactionType": "CHARGE",
            "transactionId": "5XWRJ9D1DH1R",
            "shipTaxRate": "0.00",
            "giftWrapTaxRate": "0.00",
            "legalEntityName": "AnyCompany",
            "purchasingCustomerGroupName": "AnyCompany",
            "amount": {
                "currencyCode": "USD",
                "amount": "12.00"
            },
            "paymentInstrumentType": "Visa",
            "paymentInstrumentLast4Digits": "5316",
            "buyer": {
                "id": "amzn1.account.VEYDUN7ZAJOM4EY3ZMQHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ6KWHMFFCHYXXQVVKLBCSKUFYAAKV76D63QHE2QV4ACB524OFFXFQ",
                "name": "John Doe",
                "email": "[email protected]"
            },
            "payer": {
                "id": "amzn1.account.VEYDUN7ZAJOM4EY3ZMQHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ6KWHMFFCHYXXQVVKLBCSKUFYAAKV76D63QHE2QV4ACB524OFFXFQ",
                "name": "John Doe",
                "email": "[email protected]"
            },
            "associatedTransactionDetails": [],
            "transactionLineItems": [
                {
                    "refundReason": null,
                    "totalAmount": {
                        "currencyCode": "USD",
                        "amount": "12.0"
                    },
                    "principalAmount": {
                        "currencyCode": "USD",
                        "amount": "12.0"
                    },
                    "shippingCharge": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": null,
                    "tax": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "unitPrice": {
                        "currencyCode": "USD",
                        "amount": "12.00"
                    },
                    "taxRate": "0.0",
                    "orderId": "114-2624899-7586639",
                    "unspsc": "14111803",
                    "orderLineItemId": "73617355293441",
                    "purchaseOrderNumber": "",
                    "purchaseOrderLineItemId": null,
                    "asin": "B07Y92XFRD",
                    "productTitle": "Amazon.com Thank You Mini Envelope",
                    "itemQuantity": 1,
                    "shipmentId": "MvlhRv0WK",
                    "shipmentDate": "2023-02-14T01:45:05Z",
                    "merchantLegalName": "Amazon.com Services, Inc",
                    "budgetId": null,
                    "businessOrderInfo": null
                }
            ]
        },
        {
            "marketplaceId": "ATVPDKIKX0DER",
            "transactionDate": "2023-02-13T19:58:40.025Z",
            "feedDate": "2023-02-13T20:28:49.189Z",
            "transactionType": "CHARGE",
            "transactionId": "6XZQYLZOW1S",
            "shipTaxRate": "0.00",
            "giftWrapTaxRate": "0.00",
            "legalEntityName": "John Doe",
            "purchasingCustomerGroupName": "AnyDepartment",
            "amount": {
                "currencyCode": "USD",
                "amount": "1.00"
            },
            "paymentInstrumentType": "Visa",
            "paymentInstrumentLast4Digits": "5316",
            "buyer": {
                "id": "amzn1.account.VEYDUN7ZAJOM4EY3ZMQHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ6KWHMFFCHYXXQVVKLBCSKUFYAAKV76D63QHE2QV4ACB524OFFXFQ",
                "name": "Mary Major",
                "email": "[email protected]"
            },
            "payer": {
                "id": "amzn1.account.VEYDUN7ZAJOM4EY3ZMQHEMTUNF2GINLRMZYGCNTDNB2TGN32NFQ6KWHMFFCHYXXQVVKLBCSKUFYAAKV76D63QHE2QV4ACB524OFFXFQ",
                "name": "Mary Major",
                "email": "[email protected]"
            },
            "associatedTransactionDetails": [],
            "transactionLineItems": [
                {
                    "refundReason": null,
                    "totalAmount": {
                        "currencyCode": "USD",
                        "amount": "1.0"
                    },
                    "principalAmount": {
                        "currencyCode": "USD",
                        "amount": "1.0"
                    },
                    "shippingCharge": null,
                    "regulatoryFee": null,
                    "giftWrappingCharge": null,
                    "discount": null,
                    "tax": {
                        "currencyCode": "USD",
                        "amount": "0.0"
                    },
                    "unitPrice": {
                        "currencyCode": "USD",
                        "amount": "1.00"
                    },
                    "taxRate": "0.0",
                    "orderId": "114-1540434-7879451",
                    "unspsc": "64151505",
                    "orderLineItemId": "73606364048481",
                    "purchaseOrderNumber": "",
                    "purchaseOrderLineItemId": null,
                    "asin": "B086FJV9H7",
                    "productTitle": "Amazon Gift Card - Print -We Appreciate You- Hex pattern",
                    "itemQuantity": 1,
                    "shipmentId": "FP4mS2QvZ",
                    "shipmentDate": "2023-02-13T18:50:09Z",
                    "merchantLegalName": "Amazon.com Services, Inc",
                    "budgetId": null,
                    "businessOrderInfo": null
                }
            ]
        }
    ],
    "nextPageToken": null
}

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.