Note: This is the second General Availability (GA) release of the Finances API. All new users should use the GA version instead of the alpha version. The alpha version endpoints will still be supported for a limited time, but users that are using the alpha version should make plans to migrate to the GA version. Documentation for the alpha version can now be accessed at this URL: https://developer.ebay.com/api-docs/sell/finances-v1_alpha/resources/methods.
The Finances API is used by sellers in eBay's managed payments program to retrieve seller payout information. The data provided through this public API is similar to the data that the seller will see under the Payments tab of Seller Hub in My eBay. With eBay's managed payments program, eBay manages the entire payments process, including the available payment methods, and shortly after a buyer's payment clears, eBay distributes payouts directly to the seller's preferred bank account.
Below is a summary of the three resources and six operations available through the Finances API.
- payout: a payout is distributed to the seller's bank account shortly after the buyer's payment for an order clears. A single seller payout may be for one order or numerous orders, depending on the number of orders paid for on a given day.
- getPayout: this operation retrieves details on a specific payout. The unique identifier of the payout is needed to run this operation.
- getPayouts: this operation retrieves details on multiple payouts. There are available filters to search for payouts processed within a date range, or sellers can search for payouts in different states (e.g., successful, failed, etc.). There are query parameters available for sorting and pagination control.
- getPayoutSummary: this operation retrieves counts and dollar values for payouts, and the number of monetary transactions associated with the payouts. Similar to the getPayouts operation, this operation has filters to search for payouts processed within a date range, or payouts in different states (e.g., successful, failed, etc.).
- transaction: in the Finances API, a 'transaction' can be one of five things - a sales transaction (or order), a buyer refund, a seller credit (issued by eBay), a monetary transaction involving a payment dispute initiated by a buyer through their payment provider, or a shipping label purchase. The transaction object contains identifiers for the order and payout, and the status and dollar value of the order/payout.
- getTransactions: this operation retrieves details on one or more monetary transactions. There are available filters to search for transactions by type (sale, refund, credit, payment dispute, or shipping label), transactions within a date range, transactions in different states, or sellers can search for a specific transaction according to order ID, payout ID, or buyer user name. There are query parameters available for sorting and pagination control.
- getTransactionSummary: this operation retrieves counts and dollar values for payouts, seller credits, buyer refunds, payment holds, payment disputes, and shipping labels. Similar to the getTransactions operation, this operation has filters to search for transactions by type (sale, refund, credit, payment dispute, or shipping label), transactions within a date range, transactions in different states, or sellers can search for a specific transaction according to order ID, payout ID, or buyer user name.
- seller fund summary: this resource gives the seller dollar values for all pending sales funds that are eligible for a seller payout.
- getSellerFundsSummary: this operation retrieves dollar values for funds available for payouts (but not yet in processing stage), funds being processed for payouts, funds currently locked in payment holds, and the total aggregate amount of all pending funds.
Finances API requirements and restrictions
The Finances API can be considered a 'standalone' API. Users do not have to be integrated with any other eBay public APIs in order to use the Finances API. The only user requirement is that the seller must be opted in to the eBay managed payments program. The getPaymentsProgram method of the Account API can be used to see if a seller is opted in to eBay Managed Payments.
Currently, the eBay managed payments program is only available to a limited number of sellers on the US and Germany marketplaces, and the Finances API is only relevant and usable by those sellers. This program is expected to become available to more countries and more sellers throughout 2020. See the Fall 2019 Seller Update page for more information.