Retrieving other monetary transactional data

The Finances API allows sellers to review and track information relating to monetary transactions.

Sellers can use the getTransactions and getTransactionSummary methods to retrieve information about one or more of their monetary transactions.

In addition, the getTransfer method allows sellers to retrieve the details of a specific transfer, and the charges related to that transfer. A transfer is a monetary transaction type that involves a seller transferring money to eBay for reimbursement of one or more charges. For example, when a seller reimburses eBay for a buyer refund.

Retrieving transaction details

To retrieve information about their monetary transactions, sellers can use the getTransactions method of the Finances API. See TransactionTypeEnum for a list of monetary transactions that can be retrieved with this method.

Sellers can filter the results returned and their display using the query parameters. For more information on using query parameters, see Using the filter parameter and/or Using limit, offset, and sort to display payout results.

If the call is successful, the getTransactions method returns details on one or more of a seller’s monetary transactions. Each monetary transaction is identified with its transactionId value, which can be used as a path parameter to specify the transaction retrieved in the getTransfer method (if the transactionType filter is used and set to TRANSFER). Information about the buyer, as well as the order ID associated with the transaction, is returned, along with information on each transaction such as the amount of the transaction and the transaction date.

For an example of the response payload of the getTransactions method, see the Samples section of the reference documentation.

Using the filter parameter

Sellers can use the filter query parameters individually or combined to retrieve monetary transactions. If no query parameter is set, data on all monetary transactions associated with the seller's account are returned in descending order according to transaction date. The following filter parameters are available for the getTransactions method: 

• transactionDate filters the response by monetary transactions that occurred within a specific range of dates. If the user omits the ending date, the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past.

• transactionType filters the response by a specific type of monetary transaction. See TransactionTypeEnum for supported values.

• transactionStatus filters the response by seller payouts that are in a specific state. See TransactionStatusEnum for supported values. This filter type is only applicable for sales orders.

• buyerUsername filters the response by the eBay user ID of the buyer involved in the monetary transaction.

• salesRecordReference filters the response by the unique Selling Manager identifier of the order involved in the monetary transaction. Note that although the salesRecordReference field is still returned, it is always returned as 0, except for orders prior toFebruary 1, 2020.

• payoutId filters the response by monetary transactions associated with the unique identifier of a seller payout.

• transactionId filters the response by the unique identifier of a monetary transaction. For sales orders, the orderId filter should be used instead. This filter must be used with the transactionType filter.

• orderId filters by monetary transactions associated with the unique identifier for a sales order.

• payoutReference. This filter is only supported for Mainland China sellers using split payouts. Filtering by payoutReference returns the monetary transactions associated with a payoutReference. By using this ID as a filter parameter, the user will be able to track all monetary transactions associated with both sibling payouts, including sales and refunds, if any.

An example of a combination filter would be if a seller wanted to retrieve sales within a certain date range. To do this, two filter query parameters would be used - one to filter by transaction type SALE and one to filter the date range. The call URI would look like this:

Get https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SALE}&filter=transactionDate:[2023-10-23T00:00:01.000Z..2023-09-09T00:00:01.000Z]

Using limit, offset, and sort to display payout results

Use the limit parameter to control how many results returned on a page. The default value is 20 and the maximum value is 1000.

Use the offset value to skip a specified number of results. The default value is 0, meaning that no results will be skipped. This value cannot be less than 0.

Sort is not yet available for the getTransactions method.

Retrieving Transaction Summary

By using the getTransactionSummary method, sellers can retrieve a summary of all transactions of a specified type. Sellers can filter the results returned and their display using the query parameters. For more information on using filters, see Using the filter parameter.

This retrieved transaction summary includes the total count and cumulative dollar values of seller payouts and/or seller credits and purchased eBay labels.

For an example of the response payload of the getTransactionSummary method, see the Samples section of the reference documentation.

Using the filter parameter

Sellers can use the filter query parameters individually or combined to filter the data returned in the transaction summary response. The transactionStatus filter must be used; all other filters are optional. The following filter parameters are available for the getTransactionSummary method: 

• transactionStatus only returns data in the response that pertain to the sales, payouts, and transfer status set. See TransactionStatusEnum for supported values.

• transactionDate only considers monetary transactions that occurred within a specific range of dates. If the seller omits the ending date, the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past.

• transactionType filters the response by a specific type of monetary transaction. See TransactionTypeEnum for supported values.

• buyerUsername filters the response by the eBay user ID of the buyer involved in the monetary transaction.

• salesRecordReference filters the response by the unique Selling Manager identifier of the order involved in the monetary transaction.

• payoutId filters the response by monetary transactions associated with the unique identifier of a seller payout.

• transactionId filters the response by the unique identifier of a monetary transaction. For sales orders, orderId should be used instead. This filter must be used with the transactionType filter.

• orderId filters by monetary transactions associated with the unique identifier for a sales order.

Retrieving Transfer Transaction Details

A TRANSFER is a monetary transaction that involves a seller transferring money to eBay for reimbursement for one or more charges. Using the transaction_id returned in the getTransactions method, sellers can use the GetTransfer method to retrieve details on the specific TRANSFER transaction associated with this ID. This ID must be for a TRANSFER transaction. If it is for another transaction type, the call will fail.

If the call is successful, it returns detailed information regarding the TRANSFER transaction, such as the seller’s funding source to reimburse eBay, the date and amount of the transfer, the total charges associated with the transfer, and any balance remaining after the transfer.

For an example of the response payload of the GetTransfer method, see the Samples section of the reference documentation.