Finances API v2024-06-19 Use Case Guide
How to obtain financial information for your orders using the Finances API.
API Version: v2024-06-19
What is the Finances API v2024-06-19?
The Selling Partner API for Finances (Finances API) provides financial information that is relevant to a seller's business. You can obtain financial events for a specified order or date range without having to wait until a statement period closes. Refer to the Finances API Reference for details about the operations and associated data types in the Finances API.
Key features
- Retrieve transactions by time and marketplace. Filter transactions by a range of dates, a marketplace, or both.
Tutorial: Get the latest transactions
Learn how to review transactions on a Seller's account.
Prerequisites
To complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- Approval for the Finance and Accounting role in your developer profile.
- The Finance and Accounting role selected on the App registration page for your application.
Step 1. Retrieve a list of transactions
Call the listTransactions operation to retrieve up to 500 transactions at a time. If there are more transactions available, you can retrieve them with the provided nextToken.
Query parameters
| Name | Description | Required |
|---|---|---|
postedAfter | The response includes financial events posted after (or on) this date. This date must be in ISO 8601 date-time format. The date-time must be more than two minutes before the time of the request. Type: string (date-time) | Yes |
postedBefore | The response includes financial events posted before (but not on) this date. This date must be in ISO 8601 date-time format. The date-time must be later than PostedAfter and more than two minutes before the request was submitted. If PostedAfter and PostedBefore are more than 180 days apart, the response is empty. If you include the PostedBefore parameter in your request, you must also specify the PostedAfter parameter.Default: Two minutes before the time of the request. Type: string (date-time) | No |
marketplaceId | The ID of the marketplace from which you want to retrieve transactions. Type: string | No |
nextToken | The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages.Type: string | No |
Request example
GET /finances/2024-06-19/transactions?postedAfter=2023-07-26&postedBefore=2023-09-16
Response
A successful response includes:
| Name | Description |
|---|---|
nextToken | The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages.Type: string |
transactions | A list of transactions within a given time period. Type: Transactions |
Response example
{
"transactions": [
{
"sellingPartnerMetadata": {
"sellingPartnerId": "A1WSDY9MTKXUGZ",
"marketplaceId": "AT614YYYNOC1S",
"accountType": "Standard Orders"
},
"transactionType": "Shipment",
"transactionId": "lo6cQ55-40s5sU4g_lSwkZV22qz-vCNVtjLLqAQyux4",
"transactionStatus": null,
"relatedIdentifiers": [
{
"relatedIdentifierName": "ORDER_ID",
"relatedIdentifierValue": "931-0852306-5138236"
},
{
"relatedIdentifierName": "SHIPMENT_ID",
"relatedIdentifierValue": "14178712390725"
},
{
"relatedIdentifierName": "FINANCIAL_EVENT_GROUP_ID",
"relatedIdentifierValue": "_fSsCZmGkBME7DCFtbqKLcDX-KB-M-5Pdr1NaefqCks"
}
],
"totalAmount": {
"currencyAmount": 294.46,
"currencyCode": "SEK"
},
"description": "Order Payment",
"postedDate": "2024-01-18T12:45:47Z",
"marketplaceDetails": {
"marketplaceId": "AT614YYYNOC1S",
"marketplaceName": "Amazon.se"
},
"items": [
{
"description": "SAMSUNG Galaxy Tab S6 Lite WiFi - 64GB, 4GB, Grigio",
"totalAmount": {
"currencyAmount": 294.46,
"currencyCode": "SEK"
},
"relatedIdentifiers": [
{
"itemRelatedIdentifierName": "ORDER_ADJUSTMENT_ITEM_ID",
"itemRelatedIdentifierValue": "6226957701205"
}
],
"breakdowns": [
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": 89.8,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "OurPriceTax",
"breakdownAmount": {
"currencyAmount": 80,
"currencyCode": "SEK"
},
"breakdowns": []
},
{
"breakdownType": "ShippingTax",
"breakdownAmount": {
"currencyAmount": 9.8,
"currencyCode": "SEK"
},
"breakdowns": []
}
]
},
{
"breakdownType": "ProductCharges",
"breakdownAmount": {
"currencyAmount": 320,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "OurPricePrincipal",
"breakdownAmount": {
"currencyAmount": 320,
"currencyCode": "SEK"
},
"breakdowns": []
}
]
},
{
"breakdownType": "Shipping",
"breakdownAmount": {
"currencyAmount": 39.2,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "ShippingPrincipal",
"breakdownAmount": {
"currencyAmount": 39.2,
"currencyCode": "SEK"
},
"breakdowns": []
}
]
},
{
"breakdownType": "AmazonFees",
"breakdownAmount": {
"currencyAmount": -154.54,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "FBAPerUnitFulfillmentFee",
"breakdownAmount": {
"currencyAmount": -45.54,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Base",
"breakdownAmount": {
"currencyAmount": -36.43,
"currencyCode": "SEK"
}
},
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": -9.11,
"currencyCode": "SEK"
}
}
]
},
{
"breakdownType": "Commission",
"breakdownAmount": {
"currencyAmount": -60,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Base",
"breakdownAmount": {
"currencyAmount": -60,
"currencyCode": "SEK"
}
}
]
},
{
"breakdownType": "ShippingChargeback",
"breakdownAmount": {
"currencyAmount": -49,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Base",
"breakdownAmount": {
"currencyAmount": -39.2,
"currencyCode": "SEK"
}
},
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": -9.8,
"currencyCode": "SEK"
}
}
]
}
]
}
],
"contexts": [
{
"asin": "B085V6LQPB",
"quantityShipped": 1,
"sku": "PSMM-TEST-SKU-Aug-29_08_03_14-0898",
"fulfillmentNetwork": "AFN",
"contextType": "ProductContext"
}
]
}
],
"breakdowns": [
{
"breakdownType": "Sales",
"breakdownAmount": {
"currencyAmount": 449,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": 89.8,
"currencyCode": "SEK"
},
"breakdowns": null
},
{
"breakdownType": "ProductCharges",
"breakdownAmount": {
"currencyAmount": 320,
"currencyCode": "SEK"
},
"breakdowns": null
},
{
"breakdownType": "Shipping",
"breakdownAmount": {
"currencyAmount": 39.2,
"currencyCode": "SEK"
},
"breakdowns": null
}
]
},
{
"breakdownType": "Expenses",
"breakdownAmount": {
"currencyAmount": -154.54,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "AmazonFees",
"breakdownAmount": {
"currencyAmount": -154.54,
"currencyCode": "SEK"
},
"breakdowns": null
}
]
}
],
"contexts": null
}
]
}
Tutorial: Determine which transactions make up a payment
Learn how to determine which transactions make up a payment.
Prerequisites
To complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- Approval for the Finance and Accounting role in your developer profile.
- The Finance and Accounting role selected in the App registration page for your application.
Step 1. Retrieve a list of financial event groups
Call the listFinancialEventGroups operation to retrieve up to 100 financial event groups at a time. If there are more groups available, you can retrieve them with the provided nextToken.
Query parameters
| Name | Description | Required |
|---|---|---|
MaxResultsPerPage | The maximum number of results per page. If the response exceeds the maximum number of transactions or 10 MB, the response is InvalidInput.Minimum : 1 Maximum : 100 Type: integer (int32) | No |
FinancialEventGroupStartedBefore | A date that selects financial event groups that opened before (but not at) the specified date and time, in ISO 8601 format. The date-time must be after FinancialEventGroupStartedAfter and more than two minutes before the time of request. If FinancialEventGroupStartedAfter and FinancialEventGroupStartedBefore are more than 180 days apart, no financial event groups are returned. Type: string (date-time) | No |
FinancialEventGroupStartedAfter | A date that selects financial event groups that opened after (or at) the specified date and time, in ISO 8601 format. The date-time must be more than two minutes before you submit the request. Type: string (date-time) | No |
NextToken | A string token you can use to access the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. Use this value to get the next page of results by calling the operation with this token and with the same arguments as the call that produced it. To get a complete list, call this operation until nextToken is null.Note: this operation can return empty pages. Type: string | No |
Request example
GET /finances/v0/financialEventGroups?
FinancialEventGroupStartedAfter=2024-01-27
&MaxResultsPerPage=10
Response
A successful response includes:
| Name | Description |
|---|---|
FinancialEventGroupId | A unique identifier for the financial event group. Type: string |
ProcessingStatus | The processing status of the financial event group indicates whether the balance of the financial event group is settled. Possible values: Open, ClosedType: string |
FundTransferStatus | The status of the fund transfer. Type: string |
OriginalTotal | The total amount in the currency of the marketplace in which the transactions occurred. For a closed financial group, this is the total amount of a disbursement or a charge amount. For an open financial event group, this is the current balance. Type: Currency |
ConvertedTotal | The total amount in the currency of the marketplace in which the funds were disbursed. Type: Currency |
FundTransferDate | The date and time when the disbursement or charge was initiated. Only present for closed settlements. In ISO 8601 date-time format. Type: Date |
TraceId | The trace identifier used by sellers to look up transactions externally. Type: string |
AccountTail | The account tail of the payment instrument. Type: string |
BeginningBalance | The balance at the beginning of the settlement period. Type: Currency |
FinancialEventGroupStart | The date and time at which the financial event group is opened. In ISO 8601 date-time format. Type: Date |
FinancialEventGroupEnd | The date and time at which the financial event group is closed. In ISO 8601 date-time format. Type: Date |
Response example
{
"payload": {
"FinancialEventGroupList": [
{
"BeginningBalance": {
"CurrencyAmount": 0.00,
"CurrencyCode": "USD"
},
"FinancialEventGroupId": "O-dN9Vqs_--M1HeExjpmq2fvI4jAAAANoFqBBBBB_s",
"FinancialEventGroupStart": 1.706665382522E9,
"OriginalTotal": {
"CurrencyAmount": 34.48,
"CurrencyCode": "USD"
},
"ProcessingStatus": "Open"
},
{
"BeginningBalance": {
"CurrencyAmount": 0.00,
"CurrencyCode": "USD"
},
"FinancialEventGroupId": "fqlzzk53Ab3bbJr8tfI8X0TAAAAQFT4vugWWBBBB",
"FinancialEventGroupStart": 1.706494768932E9,
"OriginalTotal": {
"CurrencyAmount": 56841.84,
"CurrencyCode": "USD"
},
"ProcessingStatus": "Open"
},
{
"AccountTail": "678",
"BeginningBalance": {
"CurrencyAmount": 0.00,
"CurrencyCode": "USD"
},
"FinancialEventGroupEnd": 1.706494768932E9,
"FinancialEventGroupId": "vQDBCUXEzvJp17lCoNXRZAAAAdbw4hA-EXMSmGBBBB",
"FinancialEventGroupStart": 1.706060973251E9,
"FundTransferDate": 1.70658124607E9,
"FundTransferStatus": "Succeeded",
"OriginalTotal": {
"CurrencyAmount": 20198.86,
"CurrencyCode": "USD"
},
"ProcessingStatus": "Closed",
"TraceId": "2Q2M4AAAAAAAAAA"
},
{
"BeginningBalance": {
"CurrencyAmount": 0.00,
"CurrencyCode": "EUR"
},
"FinancialEventGroupId": "cNY51tGJ9O--I-qKiJnHO6dmy1AAAAA0-BBBB-k",
"FinancialEventGroupStart": 1.686221326939E9,
"OriginalTotal": {
"CurrencyAmount": 0.00,
"CurrencyCode": "EUR"
},
"ProcessingStatus": "Open"
},
{
"BeginningBalance": {
"CurrencyAmount": 0.00,
"CurrencyCode": "CAD"
},
"FinancialEventGroupId": "QA8oxBDVhYpV-7VQQhOpjh1KsAAAAvdET-ZWAAAA-B",
"FinancialEventGroupStart": 1.677763011263E9,
"OriginalTotal": {
"CurrencyAmount": 0.00,
"CurrencyCode": "CAD"
},
"ProcessingStatus": "Open"
}
]
}
}
Step 2. Find the FinancialEventGroupId of the payment
FinancialEventGroupId of the paymentExamine the response to listFinancialEventGroups to find the FinancialEventGroupId of the payment you're interested in.
Step 3. Retrieve a list of transactions
To retrieve up to 500 transactions at a time, call the listTransactions operation. If there are more transactions available, you can retrieve them with the provided nextToken.
Query parameters
| Name | Description | Required |
|---|---|---|
postedAfter | The response includes financial events posted after (or on) this date. This date must be in ISO 8601 date-time format. The date-time must be more than two minutes before the time of the request. Type: string (date-time) | Yes |
postedBefore | The response includes financial events posted before (but not on) this date. This date must be in ISO 8601 date-time format. The date-time must be later than PostedAfter and more than two minutes before the request was submitted. If PostedAfter and PostedBefore are more than 180 days apart, the response is empty. If you include the PostedBefore parameter in your request, you must also specify the PostedAfter parameter.Default: Two minutes before the time of the request. Type: string (date-time) | No |
marketplaceId | The ID of the marketplace from which you want to retrieve transactions. Type: string | No |
nextToken | The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages.Type: string | No |
Request example
GET /finances/2024-06-19/transactions?postedAfter=2023-07-26&postedBefore=2023-09-16
Response
A successful response includes:
| Name | Description |
|---|---|
nextToken | The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages.Type: string |
transactions | A list of transactions within a given time period. Type: Transactions |
Response example
{
"transactions": [
{
"sellingPartnerMetadata": {
"sellingPartnerId": "A1WSDY9MTKXUGZ",
"marketplaceId": "AT614YYYNOC1S",
"accountType": "Standard Orders"
},
"transactionType": "Shipment",
"transactionId": "lo6cQ55-40s5sU4g_lSwkZV22qz-vCNVtjLLqAQyux4",
"transactionStatus": null,
"relatedIdentifiers": [
{
"relatedIdentifierName": "ORDER_ID",
"relatedIdentifierValue": "931-0852306-5138236"
},
{
"relatedIdentifierName": "SHIPMENT_ID",
"relatedIdentifierValue": "14178712390725"
},
{
"relatedIdentifierName": "FINANCIAL_EVENT_GROUP_ID",
"relatedIdentifierValue": "_fSsCZmGkBME7DCFtbqKLcDX-KB-M-5Pdr1NaefqCks"
}
],
"totalAmount": {
"currencyAmount": 294.46,
"currencyCode": "SEK"
},
"description": "Order Payment",
"postedDate": "2024-01-18T12:45:47Z",
"marketplaceDetails": {
"marketplaceId": "AT614YYYNOC1S",
"marketplaceName": "Amazon.se"
},
"items": [
{
"description": "SAMSUNG Galaxy Tab S6 Lite WiFi - 64GB, 4GB, Grigio",
"totalAmount": {
"currencyAmount": 294.46,
"currencyCode": "SEK"
},
"relatedIdentifiers": [
{
"itemRelatedIdentifierName": "ORDER_ADJUSTMENT_ITEM_ID",
"itemRelatedIdentifierValue": "6226957701205"
}
],
"breakdowns": [
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": 89.8,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "OurPriceTax",
"breakdownAmount": {
"currencyAmount": 80,
"currencyCode": "SEK"
},
"breakdowns": []
},
{
"breakdownType": "ShippingTax",
"breakdownAmount": {
"currencyAmount": 9.8,
"currencyCode": "SEK"
},
"breakdowns": []
}
]
},
{
"breakdownType": "ProductCharges",
"breakdownAmount": {
"currencyAmount": 320,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "OurPricePrincipal",
"breakdownAmount": {
"currencyAmount": 320,
"currencyCode": "SEK"
},
"breakdowns": []
}
]
},
{
"breakdownType": "Shipping",
"breakdownAmount": {
"currencyAmount": 39.2,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "ShippingPrincipal",
"breakdownAmount": {
"currencyAmount": 39.2,
"currencyCode": "SEK"
},
"breakdowns": []
}
]
},
{
"breakdownType": "AmazonFees",
"breakdownAmount": {
"currencyAmount": -154.54,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "FBAPerUnitFulfillmentFee",
"breakdownAmount": {
"currencyAmount": -45.54,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Base",
"breakdownAmount": {
"currencyAmount": -36.43,
"currencyCode": "SEK"
}
},
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": -9.11,
"currencyCode": "SEK"
}
}
]
},
{
"breakdownType": "Commission",
"breakdownAmount": {
"currencyAmount": -60,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Base",
"breakdownAmount": {
"currencyAmount": -60,
"currencyCode": "SEK"
}
}
]
},
{
"breakdownType": "ShippingChargeback",
"breakdownAmount": {
"currencyAmount": -49,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Base",
"breakdownAmount": {
"currencyAmount": -39.2,
"currencyCode": "SEK"
}
},
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": -9.8,
"currencyCode": "SEK"
}
}
]
}
]
}
],
"contexts": [
{
"asin": "B085V6LQPB",
"quantityShipped": 1,
"sku": "PSMM-TEST-SKU-Aug-29_08_03_14-0898",
"fulfillmentNetwork": "AFN",
"contextType": "ProductContext"
}
]
}
],
"breakdowns": [
{
"breakdownType": "Sales",
"breakdownAmount": {
"currencyAmount": 449,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "Tax",
"breakdownAmount": {
"currencyAmount": 89.8,
"currencyCode": "SEK"
},
"breakdowns": null
},
{
"breakdownType": "ProductCharges",
"breakdownAmount": {
"currencyAmount": 320,
"currencyCode": "SEK"
},
"breakdowns": null
},
{
"breakdownType": "Shipping",
"breakdownAmount": {
"currencyAmount": 39.2,
"currencyCode": "SEK"
},
"breakdowns": null
}
]
},
{
"breakdownType": "Expenses",
"breakdownAmount": {
"currencyAmount": -154.54,
"currencyCode": "SEK"
},
"breakdowns": [
{
"breakdownType": "AmazonFees",
"breakdownAmount": {
"currencyAmount": -154.54,
"currencyCode": "SEK"
},
"breakdowns": null
}
]
}
],
"contexts": null
}
]
}
Step 4. Review the transactions that have matching identifiers
The response to listTransactions contains the transactions array. For each transaction in this array, examine the elements of the relatedIdentifiers array. For each relatedIdentifier, if the relatedIdentifierName is EVENT_GROUP_ID, check if the relatedIdentifierValue matches the FinancialEventGroupId obtained in Step 2. Identify the appropriate FinancialEventGroupId. If it does, then this transaction is part of the payment.
Updated 16 days ago