If the filter query parameter is used to filter by payout status, only one payout status value may be used. If the filter query parameter is not used to filter by a specific payout status, cumulative values for payouts in all states are returned.
The user can also use the filter query parameter to specify a date range, and then only payouts that were processed within that date range are considered.
Input
Resource URI (production)
URI parameters
Parameter | Type | Description |
---|---|---|
filter | array of FilterField | The two filter types that can be used here are discussed below. One or both of these filter types can be used. If none of these filters are used, the data returned in the response will reflect payouts, in all states, processed within the last 90 days.
If both the payoutDate and payoutStatus filters are used, only the payouts that satisfy both criteria are considered in the results. Occurrence: Optional |
HTTP request headers
This call conditionally requires the Accept:application/json
and the X-EBAY-C-MARKETPLACE-ID
headers.
The Accept
header indicates the formats the client accepts for the response. This header pairs with the Content-Type header, which specifies the format required by eBay for the request. Currently, all eBay REST interfaces require request bodies to be formatted in JSON, and JSON is the default and only format returned in response bodies.
The X-EBAY-C-MARKETPLACE-ID
header identifies the user's business context. See https://developer.ebay.com/managed-payments for supported marketplaces. If not included with your request, the marketplace value defaults to EBAY-US
. Note that it does not indicate a language preference or end-user location.
Example:X-EBAY-C-MARKETPLACE-ID: EBAY-US
Accept:application/json
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.finances
See OAuth access tokens for more information.
Output
Output container/field | Type | Description |
---|---|---|
amount | Amount | This container shows the total value (and currency type used) of the seller payouts that match the input criteria. This field is not returned if there are no payouts that match the input criteria. Occurrence: Conditional |
amount.currency | CurrencyCodeEnum | A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. Default: The currency of the authenticated user's country. Occurrence: Conditional |
amount.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. This field is only returned if/when currency conversion was applied by eBay. Occurrence: Conditional |
amount.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. This field is only returned if/when currency conversion was applied by eBay. Occurrence: Conditional |
amount.exchangeRate | string | The exchange rate used for the monetary conversion. This field shows the exchange rate used to convert the dollar value in the value field from the dollar value in the convertedFromValue field. This field is only returned when eBay does a currency version, and a currency conversion is generally needed if the buyer is viewing, or has purchased an item on an international site. This field is only returned if/when currency conversion was applied by eBay. Occurrence: Conditional |
amount.value | string | The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type. Occurrence: Conditional |
payoutCount | integer | This integer value indicates the total count of payouts to the seller that match the input criteria. This field is always returned, even if there are no payouts that match the input criteria (its value will show 0 ). Occurrence: Always |
transactionCount | integer | This integer value indicates the total count of monetary transactions (order payments, buyer refunds, and seller credits) associated with the payouts that match the input criteria. This field is always returned, even if there are no payouts that match the input criteria (its value will show 0 ). If there is at least one payout that matches the input criteria, the value in this field will be at least 1 . Occurrence: Always |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
200 | Success |
400 | Bad Request |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
135000 | API_FINANCES | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
135002 | API_FINANCES | REQUEST | The value of payout status filter is invalid |
135004 | API_FINANCES | REQUEST | The value of payout date filter is invalid |
Warnings
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Get Counts and Values for All Payouts in All States
Input
Output
Sample 2: Get Counts and Values for Retryable Payouts Within Date Range
Input
RETRYABLE_FAILED
, and one to filter within a date range. In this sample, the date range is for the month of December 2018.
Below is the syntax to use for a non-date filter:
?filter=
filter_type:{
filter_value}
The syntax to use for a date range filter is slightly different, and is shown below. Notice the date range filter uses square brackets instead of curly brackets.
?filter=payoutDate:[
YYYY-MM-DDTHH:MM:SS.SSSZ..YYYY-MM-DDTHH:MM:SS.SSSZ]
Output
RETRYABLE_FAILED
during the month of December 2018. The value of this retryable payout is $105.98, and the total number of monetary transactions associated with this payout is 2.
Sample 3: Get Counts and Values for Failed Payouts Within Date Range
Input
TERMINAL_FAILED
, and one to filter within a date range. In this sample, the date range is for the month of December 2018.
Below is the syntax to use for a non-date filter:
?filter=
filter_type:{
filter_value}
The syntax to use for a date range filter is slightly different, and is shown below. Notice the date range filter uses square brackets instead of curly brackets.
?filter=payoutDate:[
YYYY-MM-DDTHH:MM:SS.SSSZ..YYYY-MM-DDTHH:MM:SS.SSSZ]
Output
TERMINAL_FAILED
during the month of December 2018. The value of these failed payouts is $467.90, and the total number of monetary transactions associated with these failed payouts is 10.