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:
- 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.
- 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
getTransactionsoperation. For more information, see Retrieving business transactions.
Retrieve invoice details
Call the getInvoiceDetailsByOrderLineItems operation. In the request, include the following fields:
| Name | Description | Schema | Required |
|---|---|---|---|
orderLineItems | List 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 > array | Yes |
When multiple line items are included in one invoice, the set of request inputs for each item (different
orderLineItemIdvalues all associated with the sameorderIdandshipmentId) 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 theinvoiceNumberthat 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:
| Name | Description | Schema | Required |
|---|---|---|---|
invoiceDetailsByOrderLineItems | Lists the invoices that includes order line item and invoice details. | < InvoiceDetailsOfOrderLineItem > array | Yes |
In JP, the invoiceDetails object of the response also includes the following data for each invoice retrieved:
| Name | Description | Schema |
|---|---|---|
invoiceNumber | The ID number of the Invoice or Credit Memo. | string |
invoiceDate | The date the Invoice or Credit Memo was issued. | string (date-time) |
consolidatedInvoiceDetails | This contains the consolidated invoice details if the order is enabled for purchase/periodic consolidation. | ConsolidatedInvoiceDetails |
invoiceType | Indicate 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 |
associatedInvoiceNumber | The 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 |
associatedInvoiceDate | The 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) |
invoiceIssuer | The 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 |
billToAddress | The address information to which the Invoice or Credit Memo was issued. Available for JP region only. | PhysicalAddress |
sellerInformation | The details associated with the original seller of the products. Available for JP region only. | MerchantDetail |
orderDate | The 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) |
currencyCode | The three-digit currency code, in ISO 4217 format. Available for JP region only. | string |
invoiceTotal | Sum of all charges specified in the Invoice, including products, applicable taxes, and any additional fees. Available for JP region only. | string |
tax | The tax amount and rate the buyer pays for the product and services. Available for JP region only. | < TaxDetail > array |
transactionDataItems | The invoice line item details including ASIN, price, unit, discount, and fee. Available for JP region only. | < TransactionDataItem > array |
fees | The 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.
Updated about 2 months ago