Skip to main content

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

Sellers can use the getPayout, getPayouts, getPayoutSummary methods to retrieve details on payouts to their bank account.

In addition, the getSellerFundsSummary method can be used to retrieve all pending funds that have not been distributed through a seller payout.

Retrieving payout details

Sellers can use the getPayout method to retrieve the details of a specific seller payout. The payout being retrieved is specified by the payout_Id at the end of the call URI. This ID can be found in the getPayouts response, or on the Seller Hub.

A successful call returns details about the specified seller payout. This includes information such as the status and amount of the payout, the payout date, the transaction count associated with the payout, and the instrument set to receive the payout.

In addition, the bank reference ID for the payout is returned, so that the seller can track the payout with the bank if necessary.

For an example of the response payload of the getPayout call, see the Samples section of the reference documentation.

Retrieving details on multiple payouts

Sellers can retrieve details on one or more payouts using the getPayouts method. This method returns payout details for each seller payout retrieved. Sellers can use the filter query parameter to filter the results by a specific date or status. For more information on using filters, see Using the filter parameter.

The payout_id value returned from this method can be used as a path parameter in the getPayout method to retrieve details on that specific payout.

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

Using the filter parameter

Sellers can use the filter query parameter to retrieve payouts processed within a specific date range, and/or retrieve payouts in a specific state. The following filter parameters are available for the getPayouts method: 

  • payoutDate filters the response by payouts 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.

  • lastAttemptedPayoutDate filters the response by attempted payouts that failed within a specific range of dates. In order to use this filter, the payoutStatus filter must also be used and its value must be set to RETRYABLE_FAILED. This filter is only applicable (and will return results) if one or more seller payouts have failed, but are retryable.

  • payoutStatus filters by payouts that are in a particular state. Only one payout state can be specified with this filter. For supported payoutStatus values, see PayoutStatusEnum.

  • payoutReference. This filter is only supported for Mainland China sellers using split payouts. Filtering by payoutReference returns the two true(actual) payouts associated with the payoutReference ID. This parameter can support up to 200 payoutReference inputs.

Note: If no payouts match the input criteria, and empty payload is returned.

Using limit, offset, and sort to display payout results

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

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

Use the sort value to select the order for returning the results. By default, results are returned in descending order according to the payout date/last attempted payout date. To view in ascending order instead, you would include the sort query parameter and then set the value of its field parameter to payoutDate or last attemptedPayoutDate.

Retrieving payout summary

Sellers can use the getPayoutSummary method to retrieve the cumulative values for payouts in a particular state or all states, or during a particular time range.

To do so, a seller must make a getPayoutSummary call. There are no required path parameters for this method. Optionally, sellers can use the filter query parameter to filter by a specific payout status or date. For more information on using filters, see Using the filter parameter.

A successful call returns a payout summary that includes the total number of all recent payouts and the total number of monetary transactions associated with these payouts, such as sales, refunds, or credits. The total dollar value associated with these payouts is also returned.

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

Using the filter parameter

Sellers can use the filter query parameter to filter by payoutStatus and/or by payoutDate. The following filter parameters are available for the getPayoutSummary method: 

  • payoutStatus returns only the payouts in a particular state. Only one payout state can be specified with this filter. For supported values see PayoutStatusEnum.

  • payoutDate returns payouts processed 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.

For example, if a seller wanted to retrieve terminally failed payouts within a specific date range, the call URI would look like this:

GET https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutStatus:{TERMINAL_FAILED}&filter=payoutDate:[2018-12-01T00:00:01.000Z..2018-12-31T00:00:01.000Z]

Retrieving pending funds

Sellers can call the getSellerFundsSummary method to retrieve all pending funds that have not been distributed through a seller payout.

There are no input parameters for this method.

If the call is successful the output shows the total amount of all pending funds that will eventually be distributed to a seller’s account (totalFunds). This is broken down into the total amount of available funds that will be processed (availableFunds), the total amount of funds currently being processed for a pending payout (processingFunds), and funds that are currently on hold (fundsOnHold).

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