Retrieving invoice details in JP region

In the Japanese (JP) region, the Reconciliation API getInvoiceDetailsByOrderLineItems operation returns fields that allow you to comply with Japanese tax regulations. This data includes fields such as tax, transaction data items, and associated fees. With this data, you can automate the reconciliation process by retrieving tax-compliant invoice information.

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

📘

When multiple line items are included in one invoice, the set of request inputs for each item (different orderLineItemId values all associated with the same orderId and shipmentId) would return the same invoice data in response. If you would like to avoid ingesting the same invoice data multiple times, you can filter out the invoiceNumber that has already been retrieved so that you only send inputs associated with unique invoices.

POST https://jp.business-api.amazon.com/reconciliation/2021-01-08/invoices
      
{
  "orderLineItems": [
    {
      "orderId": "123-2339549-4654220",
      "orderLineItemId": "7925364691123",
      "shipmentId": "AbCVyqSXJ"
    }
  ]
}
import requests

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

payload = {
   "orderLineItems": [
        {
            "orderId": "123-2339549-4654220",
            "orderLineItemId": "7925364691123",
            "shipmentId": "AbCVyqSXJ"
        }
    ]
}

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 response includes the following details:

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

In JP, the invoiceDetails object of the response also includes the following data for each invoice retrieved:

NameDescriptionSchema
invoiceNumberThe ID number of the Invoice or Credit Memo.string
invoiceDateThe date the Invoice or Credit Memo was issued.string (date-time)
consolidatedInvoiceDetailsThis contains the consolidated invoice details if the order is enabled for purchase/periodic consolidation.ConsolidatedInvoiceDetails
invoiceTypeIndicate that the data returned is Invoice or Credit Memo. Possible values: STANDARD (for Invoice) and CREDIT_MEMO (for Credit Memo). Available for JP region only.InvoiceType
associatedInvoiceNumberThe original Invoice number associated with the Credit Memo. This field shows value if the invoiceType is CREDIT_MEMO. For STANDARD invoice, this field shows "null". Available for JP region only.string
associatedInvoiceDateThe original Invoice date associated with the Credit Memo. This field shows value if the invoiceType is CREDIT_MEMO. For STANDARD invoice, this field shows "null". Available for JP region only.string (date-time)
invoiceIssuerThe details associated with the issuer of the Invoice. This section returns Amazon Japan details when the original seller has a Tax Registration Number (Japan Consumtion Tax number). This behavior applies even when the original seller is a 3P seller as intermediary issuance by Amazon. See sellerInformation for details of the original seller. Available for JP region only.InvoiceIssuerDetail
billToAddressThe address information to which the Invoice or Credit Memo was issued. Available for JP region only.PhysicalAddress
sellerInformationThe details associated with the original seller of the products. Available for JP region only.MerchantDetail
orderDateThe date and time the order was placed. The date follows the ISO 8601 format, yyyy-MM-ddThh:mm:ssZ. Available for JP region only.string (date-time)
currencyCodeThe three-digit currency code, in ISO 4217 format. Available for JP region only.string
invoiceTotalSum of all charges specified in the Invoice, including products, applicable taxes, and any additional fees. Available for JP region only.string
taxThe tax amount and rate the buyer pays for the product and services. Available for JP region only.< TaxDetail > array
transactionDataItemsThe invoice line item details including ASIN, price, unit, discount, and fee. Available for JP region only.< TransactionDataItem > array
feesThe invoice level fee the buyer pays for the product and services. Available for JP region only.< InvoiceLevelFeeDetail > array

{
    "invoiceDetailsByOrderLineItems": [
        {
            "orderLineItem": {
                "orderId": "250-XXXXXXX-XXXXXXX",
                "orderLineItemId": "7XXXXXXXXXXXX",
                "shipmentId": " XXXXXXXXX"
            },
            "invoiceDetails": [
                {
                    "invoiceNumber": "JP36BXXXXXXXXX",
                    "invoiceDate": "2023-07-20T21:26:49.76Z",
                    "consolidatedInvoiceDetails": null,
                    "invoiceType": "STANDARD",
                    "associatedInvoiceNumber": null,
                    "associatedInvoiceDate": null,
                    "invoiceIssuer": {
                        "name": "アマゾンジャパン合同会社",
                        "registrationNumber": "T3040001028447"
                    },
                    "billToAddress": {
                        "fullName": "Test Purchase",
                        "phoneNumber": "03-1234-5678",
                        "companyName": null,
                        "addressLine1": "test1",
                        "addressLine2": "test2",
                        "addressLine3": null,
                        "city": null,
                        "stateOrRegion": "東京都",
                        "postalCode": "000-0000",
                        "countryCode": "JP"
                    },
                    "sellerInformation": {
                        "name": "アマゾンジャパン合同会社",
                        "registrationNumber": "T3040001028123"
                    },
                    "orderDate": "2023-07-18T15:18:42Z",
                    "currencyCode": "JPY",
                    "invoiceTotal": "2910.0",
                    "tax": [
                        {
                            "rate": "0.1",
                            "inclusiveTotal": {
                                "currencyCode": "JPY",
                                "amount": "2910.0"
                            },
                            "exclusiveTotal": {
                                "currencyCode": "JPY",
                                "amount": "2646.0"
                            },
                            "amount": {
                                "currencyCode": "JPY",
                                "amount": "264.0"
                            }
                        }
                    ],
                    "transactionDataItems": [
                        {
                            "taxRate": "0.1",
                            "unit": 3,
                            "asin": "Bxxxxxxxxx",
                            "title": "Amazon",
                            "unitTaxInclusivePrice": {
                                "currencyCode": "JPY",
                                "amount": "970.0"
                            },
                            "unitTaxExclusivePrice": {
                                "currencyCode": "JPY",
                                "amount": "882"
                            },
                            "unitTaxAmount": {
                                "currencyCode": "",
                                "amount": "0"
                            },
                            "totalAmount": {
                                "currencyCode": "JPY",
                                "amount": "2910.0"
                            },
                            "discount": null,
                            "apportionment": [
                                {
                                    "orderLineItemId": "7XXXXXXXXXXXX",
                                    "lineNumber": 1,
                                    "units": 3,
                                    "unitPrice": {
                                        "currencyCode": "JPY",
                                        "amount": "882.0"
                                    },
                                    "taxAmount": {
                                        "currencyCode": "JPY",
                                        "amount": "88.0"
                                    }
                                }
                            ],
                            "fees": []
                        }
                    ],
                    "fees": [
                        {
                            "feeType": "SHIPPING",
                            "tax": {
                                "rate": "0.1",
                                "inclusiveTotal": {
                                    "currencyCode": "JPY",
                                    "amount": "410.0"
                                },
                                "exclusiveTotal": {
                                    "currencyCode": "JPY",
                                    "amount": "374.0"
                                },
                                "amount": {
                                    "currencyCode": "JPY",
                                    "amount": "36.0"
                                }
                            },
                            "discount": {
                                "currencyCode": "JPY",
                                "amount": "-410.0"
                            },
                            "apportionment": [
                                {
                                    "taxExclusiveFee": {
                                        "currencyCode": "JPY",
                                        "amount": "374.0"
                                    },
                                    "taxAmount": {
                                        "currencyCode": "JPY",
                                        "amount": "36.0"
                                    }
                                }
                            ]
                        }
                    ]
                },
                {
                    "invoiceNumber": "JP32XXXXXXXXX",
                    "invoiceDate": "2023-10-11T03:01:44.031Z",
                    "consolidatedInvoiceDetails": null,
                    "invoiceType": "CREDIT_MEMO",
                    "associatedInvoiceNumber": "JP36BXXXXXXXXX",
                    "associatedInvoiceDate": "2023-07-20T21:26:49.76Z",
                    "invoiceIssuer": {
                        "name": "アマゾンジャパン合同会社",
                        "registrationNumber": "T3040001028447"
                    },
                    "billToAddress": {
                        "fullName": "Test Purchase",
                        "phoneNumber": "03-1234-5678",
                        "companyName": null,
                        "addressLine1": "test1",
                        "addressLine2": "test2",
                        "addressLine3": null,
                        "city": null,
                        "stateOrRegion": "東京都",
                        "postalCode": "000-0000",
                        "countryCode": "JP"
                    },
                    "sellerInformation": {
                        "name": "アマゾンジャパン合同会社",
                        "registrationNumber": "T3040001028447"
                    },
                    "orderDate": "2023-07-18T15:18:42Z",
                    "currencyCode": "JPY",
                    "invoiceTotal": "970.00",
                    "tax": [
                        {
                            "rate": "0.1",
                            "inclusiveTotal": {
                                "currencyCode": "JPY",
                                "amount": "970.0"
                            },
                            "exclusiveTotal": {
                                "currencyCode": "JPY",
                                "amount": "882.0"
                            },
                            "amount": {
                                "currencyCode": "JPY",
                                "amount": "88.0"
                            }
                        }
                    ],
                    "transactionDataItems": [
                        {
                            "taxRate": "0.1",
                            "unit": 1,
                            "asin": "Bxxxxxxxxx",
                            "title": "Amazon",
                            "unitTaxInclusivePrice": {
                                "currencyCode": "JPY",
                                "amount": "970.0"
                            },
                            "unitTaxExclusivePrice": {
                                "currencyCode": "JPY",
                                "amount": "882"
                            },
                            "unitTaxAmount": {
                                "currencyCode": "",
                                "amount": "0"
                            },
                            "totalAmount": {
                                "currencyCode": "JPY",
                                "amount": "970.00"
                            },
                            "discount": null,
                            "apportionment": [
                                {
                                    "orderLineItemId": "7XXXXXXXXXXXX",
                                    "lineNumber": 1,
                                    "units": 1,
                                    "unitPrice": {
                                        "currencyCode": "JPY",
                                        "amount": "882.0"
                                    },
                                    "taxAmount": {
                                        "currencyCode": "JPY",
                                        "amount": "88.0"
                                    }
                                }
                            ],
                            "fees": []
                        }
                    ],
                    "fees": []
                }
            ]
        }
    ]
}

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.