HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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:

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

NameDescriptionRequired
postedAfterThe 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
postedBeforeThe 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
marketplaceIdThe ID of the marketplace from which you want to retrieve transactions.
Type: string
No
nextTokenThe 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:

NameDescription
nextTokenThe 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
transactionsA 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:

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

NameDescriptionRequired
MaxResultsPerPageThe 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
FinancialEventGroupStartedBeforeA 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
FinancialEventGroupStartedAfterA 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
NextTokenA 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

{
  "Operation": "com.amazon.mws.finances._2015_05_01#ListFinancialEventGroups",
  "Service": "com.amazon.mws.finances._2015_05_01#MWSFinancesService",
  "Input": {
    "SellerId": "A354ABCDEFGH",
    "MaxResultsPerPage": 10,
    "FinancialEventGroupStartedAfter": 1706332468
  }
}

Response

A successful response includes:

NameDescription
FinancialEventGroupIdA unique identifier for the financial event group.
Type: string
ProcessingStatusThe processing status of the financial event group indicates whether the balance of the financial event group is settled.

Possible values: Open, Closed
Type: string
FundTransferStatusThe status of the fund transfer.
Type: string
OriginalTotalThe 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
ConvertedTotalThe total amount in the currency of the marketplace in which the funds were disbursed.
Type: Currency
FundTransferDateThe date and time when the disbursement or charge was initiated. Only present for closed settlements. In ISO 8601 date-time format.
Type: Date
TraceIdThe trace identifier used by sellers to look up transactions externally.
Type: string
AccountTailThe account tail of the payment instrument.
Type: string
BeginningBalanceThe balance at the beginning of the settlement period.
Type: Currency
FinancialEventGroupStartThe date and time at which the financial event group is opened. In ISO 8601 date-time format.
Type: Date
FinancialEventGroupEndThe date and time at which the financial event group is closed. In ISO 8601 date-time format.
Type: Date

Response example

{
  "Output": {
    "__type": "com.amazon.mws.finances._2015_05_01#ListFinancialEventGroupsResponse",
    "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"
      }
    ]
  },
  "Version": "1.0"
}

Step 2. Find the FinancialEventGroupId of the payment

Examine 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

NameDescriptionRequired
postedAfterThe 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
postedBeforeThe 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
marketplaceIdThe ID of the marketplace from which you want to retrieve transactions.
Type: string
No
nextTokenThe 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:

NameDescription
nextTokenThe 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
transactionsA 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.