GET/billing_activity
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.
Note: The Finances API does not support Team Access. Financial information, such as payouts or transactions, is only returned for the user that makes the call. You cannot use any of the methods in this API to return financial information for another user.
This method retrieves filtered billing activities of the seller. Returned results are filtered through query parameters such as date range, activity ID, listing ID, or order ID. Sorting and pagination features help organize and navigate returned activities efficiently.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| filter | array of FilterField | This required field specifies which results to return in the response. Only one of the following four filter values must be used. A user can either retrieve all billing activity within a date range, or they can retrieve billing activity related to a specific eBay order, eBay listing, or they can retrieve information on a specific billing activity.
Examples IDs: filter=activityID:{12**56}Date range: filter=transactionDate:[2025-10-01T00:00:00Z..2025-10-31T23:59:59Z] Occurrence: Required |
| sort | array of SortField | By default, transactions that match the input criteria are sorted in descending order according to the transaction date (most recent transactions returned first). To view transactions in ascending order instead (oldest transactions first), include the sort query parameter and set its value to sort=transactionDate. For example (ascending order):filter=transactionDate:[2025-11-01T00:00:01.000Z..2025-11-12T00:00:01.000Z]&sort=transactionDateTransactions can only be sorted according to transaction date. If omitted, defaults to descending order (most recent transactions returned first). Occurrence: Optional |
| limit | string | Sets the maximum number of records to return per page of data. Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, with offset set to Although this field is optional, if omitted the default value of Minimum: 1Maximum: 200Default: 100 Occurrence: Optional |
| offset | string | Specifies the number of records to skip in the result set. This is used with the limit field to control the pagination of the output. For example:
If this parameter is not set, its value defaults to Note: This feature employs a zero-based list, where the first activity in the list has an offset of 0. Default: 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.
| Header | Type | Description |
|---|---|---|
| Accept-Language | string | This header indicates the natural language and locale preferred by the user for the response. For more information, see the Accept-Language header in HTTP request headers and Marketplace ID values. If not provided, defaults to en-US. Occurrence: Optional |
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/field | Type | Description |
|---|---|---|
| billingActivities | array of BillingActivityLineItem | A list of billing activity entries that meet the filter criteria. Billing activity will include fees, credits, and promotional offers applied to the seller's account. Occurrence: Always |
| billingActivities.amount | Amount | This container shows the amount of the fee or credit. The value and currency are always returned. If the buyer is in one country and purchases from an eBay marketplace that uses a different currency, the response also includes the converted-from and converted-to fields, along with the exchange rate. Occurrence: Always |
| billingActivities.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. Occurrence: Conditional |
| billingActivities.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. Occurrence: Conditional |
| billingActivities.amount.convertedToCurrency | CurrencyCodeEnum | 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 Occurrence: Conditional |
| billingActivities.amount.convertedToValue | string | 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. Occurrence: Conditional |
| billingActivities.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. Occurrence: Always |
| billingActivities.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. Occurrence: Conditional |
| billingActivities.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: Always |
| billingActivities.billingTransactionDate | string | This timestamp indicates the date/time when eBay processed the transaction. Occurrence: Always |
| billingActivities.billingTransactionId | string | This field provides a unique identifier of the billing transaction. If a seller wants to view details on a specific billing transaction, they can use the actvityId filter and pass in a specific billingTransactionId value. Occurrence: Always |
| billingActivities.bookingEntry | string | The value returned in this field will indicate if the billing transaction is a debit against the seller's account, or a credit. A debit is much more prevalent than a credit, but sometimes a listing fee will get reversed and they will get a credit for this fee. Possible values:
Occurrence: Always |
| billingActivities.feeType | string | This field describes the type of fee associated with the transaction. An example value is Occurrence: Always |
| billingActivities.feeTypeDescription | string | This field contains the human-readable description of the fee type associated with the transaction. For example, Occurrence: Always |
| billingActivities.listingId | string | The unique identifier of the eBay listing associated with the billing transaction. This field is returned if the fee is associated with a listing. Occurrence: Conditional |
| billingActivities.orderId | string | The unique identifier of the eBay order associated with the billing transaction. This field is returned if the fee is associated with an order. Occurrence: Conditional |
| billingActivities.promotionalOffers | array of DiscountDetail | A list of seller promotional offers applicable for the billing transaction. Occurrence: Conditional |
| billingActivities.promotionalOffers.amount | Amount | This container shows the amount of the promotion. The value and currency are always returned. If the buyer is in one country and purchases from an eBay marketplace that uses a different currency, the response also includes the converted-from and converted-to fields, and the exchange rate. Occurrence: Conditional |
| billingActivities.promotionalOffers.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. Occurrence: Conditional |
| billingActivities.promotionalOffers.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. Occurrence: Conditional |
| billingActivities.promotionalOffers.amount.convertedToCurrency | CurrencyCodeEnum | 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 Occurrence: Conditional |
| billingActivities.promotionalOffers.amount.convertedToValue | string | 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. Occurrence: Conditional |
| billingActivities.promotionalOffers.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. Occurrence: Always |
| billingActivities.promotionalOffers.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. Occurrence: Conditional |
| billingActivities.promotionalOffers.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: Always |
| billingActivities.promotionalOffers.offerType | string | The type of promotional discount applied through the activity's promotional offer amount. Examples include offer types such as Occurrence: Conditional |
| count | integer | An integer representing the number of billing activity items returned in this response page. Occurrence: Always |
| limit | integer | The value of the limit parameter. This is the maximum number of line items, as filtered, of billing transactions to return per page from the result set. Occurrence: Always |
| next | string | The URI for the next page of results starting with the resource name. This URI is returned if there is an additional page of results in the result set. Occurrence: Conditional |
| offset | integer | The value of the offset parameter. This field indicates how many results were skipped in the response. If an offset parameter was not included in the request, this value will default to Occurrence: Always |
| prev | string | The URI for the previous page of results starting with the resource name. This URI is returned if there is a previous page of results in the result set. Occurrence: Conditional |
| total | integer | The total number of billing transactions available that match the filter criteria. Note: When the total value exceeds the limit value, there are multiple pages of results. 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 | OK |
| 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 | REQUEST | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 135005 | API_FINANCES | REQUEST | The sort value is invalid. See documentation for supported values. |
| 135015 | API_FINANCES | REQUEST | At least one filter parameter must be used. See documentation for supported filter types. |
| 135016 | API_FINANCES | REQUEST | Invalid filter format. See documentation for correct format for each filter type. |
| 135017 | API_FINANCES | REQUEST | Invalid filter type. See documentation for supported filter types. |
| 135018 | API_FINANCES | REQUEST | Only one filter type can be used at a time. |
| 135019 | API_FINANCES | REQUEST | Invalid date format. Date must be in ISO-8601 format (e.g., 2024-10-23T00:00:01.000Z). |
| 135020 | API_FINANCES | REQUEST | There is a syntax error in your date_range filter. Please see documentation for proper syntax. |
| 135021 | API_FINANCES | REQUEST | The starting date range cannot be set back further than 120 days in the past. |
| 135022 | API_FINANCES | REQUEST | Invalid limit value. Limit must be between 1 and 200. |
| 135023 | API_FINANCES | REQUEST | Invalid offset value. If provided, Offset must be 0 or greater. |
| 135025 | API_FINANCES | REQUEST | Invalid date range: the end date occurs before the start date. |
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 billing activities of the seller
This sample retrieves detailed billing activities that occurred within a specified date range sorted by oldest transactions first.
Input
The input provides the following query parameters (no input payload).
- Retrieves billing transactions within a specific date range:
filter=transactionDate [start..end] - Sorts response returning oldest transactions first:
sort=transactionDate - Controls pagination:
limitandoffsetparameters
GEThttps://api.ebay.com/sell/finances/v1/billing_activity?limit=10&sort=transactionDate&filter=transactionDate:[2025-08-27T21:54:01.174Z..2025-08-27T21:59:07.532Z]&offset=30
Output
If the call is successful, an array of activities matching the specified criteria are returned. The offset of 30 and a limit of 10 was sent in the request, items 31-40 are returned.