Skip to main content

GET/payout_summary

Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including all Finances API methods. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.


This method is used to retrieve cumulative values for payouts in a particular state, or all states. The metadata in the response includes total payouts, the total number of monetary transactions (sales, refunds, credits) associated with those payouts, and the total dollar value of all payouts.

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

GET https://apiz.ebay.com/sell/finances/v1/payout_summary?

This method is supported in Sandbox environment. To access the endpoint, just replace the apiz.ebay.com root URI with apiz.sandbox.ebay.com

URI parameters

ParameterTypeDescription
filterarray of FilterFieldThe 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 all previous payouts in all states:
  • payoutDate: consider payouts processed within a specific range of dates. The date format to use is YYYY-MM-DDTHH:MM:SS.SSSZ. Below is the proper syntax to use if filtering by a date range:

    https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutDate:[2018-12-17T00:00:01.000Z..2018-12-24T00:00:01.000Z]

    Alternatively, the user could omit the ending date, and 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.
  • payoutStatus: consider only the payouts in a particular state. Only one payout state can be specified with this filter. For supported payoutStatus values, see PayoutStatusEnum.

    Below is the proper syntax to use if filtering by payout status:

    https://apiz.ebay.com/sell/finances/v1/payout_summary?filter=payoutStatus:{SUCCEEDED}

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

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
X-EBAY-C-MARKETPLACE-IDstringThis header identifies the seller's eBay marketplace.

See HTTP request headers for the marketplace ID values.

Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.

Occurrence: Required

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.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
amountAmount

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.convertedFromCurrencyCurrencyCodeEnum

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.convertedFromValuestring

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.convertedToCurrencyCurrencyCodeEnum

Note: This field is only applicable for Mainland China sellers with an available CNY Bank payment instrument. This response can only have a value of CNY.The three-letter ISO 4217 code representing the currency of the amount in the convertedToValue field.

This field is only returned for payouts to bank accounts when currency conversion was applied by eBay.

Occurrence: Conditional

amount.convertedToValuestring

Note: This field is only applicable for Mainland China sellers with an available CNY Bank payment instrument. This response only returns value in CNY.The monetary value after any conversion is performed, in the currency specified by the convertedToCurrency field. This value is the converted amount.

The field is only returned for payouts to bank accounts when currency conversion was applied by eBay.

Occurrence: Conditional

amount.currencyCurrencyCodeEnum

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.exchangeRatestring

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.

For sellers in mainland China, this field shows shows the exchange rate to convert the dollar value in the value field to the CNY value in the convertedToValue 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.valuestring

The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.

Occurrence: Conditional

payoutCountinteger

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

transactionCountinteger

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.

StatusMeaning
200Success
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
135000API_FINANCESAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
135002API_FINANCESREQUESTThe value of payout status filter is invalid
135004API_FINANCESREQUESTThe value of payout date filter is invalid

Warnings

This call has no 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

This call sample retrieves the total number of all recent payouts, the dollar amount associated with these payouts, and the total number of monetary transactions associated with these payouts. No filters are used.

Input

Only the GET HTTP method and the endpoint are used. No filter parameters are used, so all recent payouts in all states will be retrieved.

GEThttps://apiz.ebay.com/sell/finances/v1/payout_summary

Output

The output indicates that there have been 10 recent payouts, and the cumulative value of these payouts is $1157.74. The total number of monetary transactions associated with these payouts is 28.

Sample 2: Get Counts and Values for Retryable Payouts Within Date Range

This call sample retrieves counts and values for seller payouts that failed, but ones which will be retried. Two filter parameters are used and configured to return retryable payouts within a stated date range.

Input

For this sample, two filter query parameters are used - one to filter by the payout status of 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]

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

Output

The output indicates that there has only been one seller payout with a status of 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

This call sample retrieves counts and values for seller payouts that failed and will not be retried. Two filter parameters are used and configured to return terminally failed payouts within a stated date range.

Input

For this sample, two filter query parameters are used - one to filter by the payout status of 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]

GEThttps://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]

Output

The output indicates that there were four seller payouts with a status of 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.