There are also pagination and sort query parameters that allow users to further control the monetary transactions that are returned in the response.
If no monetary transactions match the input criteria, an http status code of 204 No Content is returned with no response payload.
Input
Resource URI (production)
URI parameters
Parameter | Type | Description |
---|---|---|
limit | integer | The number of monetary transactions to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, if offset is set to 10 and limit is set to 10 , the method retrieves monetary transactions 11 thru 20 from the result set. Note: This feature employs a zero-based list, where the first item in the list has an offset of 0 . If an orderId, transactionId, or payoutId filter is included in the request, any limit value will be ignored. Maximum: 1000 Default: 20 Occurrence: Optional |
offset | integer | This integer value indicates the actual position that the first monetary transaction returned on the current page has in the results set. So, if you wanted to view the 11th monetary transaction of the result set, you would set the offset value in the request to 10 . In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10 , the method retrieves transactions 31 thru 40 from the resulting collection of transactions. Note: This feature employs a zero-based list, where the first item in the list has an offset of 0 .Default: 0 (zero) Occurrence: Optional |
filter | array of FilterField | Numerous filters are available for the getTransactions method, and these filters are discussed below. One or more of these filter types can be used. If none of these filters are used, all monetary transactions from the last 90 days are returned:
Occurrence: Optional |
sort | array of SortField | Sorting is not yet available for the getTransactions method. By default, monetary transactions that match the input criteria are sorted in descending order according to the transaction date. Occurrence: Optional |
HTTP request headers
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 |
---|---|---|
href | string | The URI of the getTransactions method request that produced the current page of the result set. Occurrence: Always |
limit | integer | The maximum number of monetary transactions that may be returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 20 . Note: If this is the last or only page of the result set, the page may contain fewer monetary transactions than the limit value. To determine the number of pages in a result set, divide the total value (total number of monetary transactions matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total monetary transactions) and the limit value was 50 (show 50 monetary transactions per page), the total number of pages in the result set is three, so the seller would have to make three separate getTransactions calls to view all monetary transactions matching the input criteria. Maximum: 200 Default: 20 Occurrence: Always |
next | string | The getTransactions method URI to use if you wish to view the next page of the result set. This field is only returned if there is a next page of results to view based on the current input criteria. Occurrence: Conditional |
offset | integer | This integer value indicates the actual position that the first monetary transaction returned on the current page has in the results set. So, if you wanted to view the 11th monetary transaction of the result set, you would set the offset value in the request to 10 . In the request, you can use the offset parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to 30 and limit is set to 10 , the method retrieves monetary transactions 31 thru 40 from the resulting collection of monetary transactions. Note: This feature employs a zero-based list, where the first item in the list has an offset of 0 .Default: 0 (zero) Occurrence: Always |
prev | string | The getTransactions method URI to use if you wish to view the previous page of the result set. This field is only returned if there is a previous page of results to view based on the current input criteria. Occurrence: Conditional |
total | integer | This integer value is the total amount of monetary transactions in the result set based on the current input criteria. Based on the total number of monetary transactions that match the criteria, and on the limit and offset values, there may be additional pages in the results set. Occurrence: Always |
transactions | array of Transaction | An array of one or more monetary transactions that match the input criteria. Details for each monetary transaction may include the unique identifier of the order associated with the monetary transaction, the status of the transaction, the amount of the order, the order's buyer, and the unique identifier of the payout (if a payout has been initiated/issued for the order). Occurrence: Always |
transactions.amount | Amount | This container shows the dollar value and currency type of the monetary transaction. This field is always returned even when eBay has yet to initiate a payout for the order. Occurrence: Always |
transactions.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 |
transactions.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 |
transactions.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 |
transactions.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 |
transactions.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 |
transactions.bookingEntry | BookingEntryEnum | The enumeration value returned in this field indicates if the monetary transaction amount is a (CREDIT ) or a (DEBIT ) to the seller's account. Typically, the SALE and CREDIT transaction types are credits to the seller's account, and the REFUND , DISPUTE , SHIPPING_LABEL , and TRANSFER transaction types are debits to the seller's account. Occurrence: Always |
transactions.buyer | Buyer | This is the unique eBay user ID for the buyer who purchased the order. This field is not returned for TRANSFER monetary transaction types. Occurrence: Conditional |
transactions.buyer.username | string | The eBay user ID of the order's buyer. Occurrence: Always |
transactions.feeType | FeeTypeEnum | The type of fee. Occurrence: Conditional |
transactions.orderId | string | The unique identifier of the eBay order associated with the monetary transaction. Occurrence: Conditional |
transactions.orderLineItems | array of OrderLineItem | This array shows the fees that are deducted from a seller payout for each line item in an order. Occurrence: Conditional |
transactions.orderLineItems.feeBasisAmount | Amount | This is the total amount of fees accrued for the order line item and deducted from a seller payout. All of the fees under the marketplaceFees container should equal this amount. Occurrence: Conditional |
transactions.orderLineItems.feeBasisAmount.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 |
transactions.orderLineItems.feeBasisAmount.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 |
transactions.orderLineItems.feeBasisAmount.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 |
transactions.orderLineItems.feeBasisAmount.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 |
transactions.orderLineItems.feeBasisAmount.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 |
transactions.orderLineItems.lineItemId | string | The unique identifier of an order line item. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees | array of Fee | An array of all fees accrued for the order line item and deducted from a seller payout. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.amount | Amount | The amount of the fee. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.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 |
transactions.orderLineItems.marketplaceFees.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 |
transactions.orderLineItems.marketplaceFees.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 |
transactions.orderLineItems.marketplaceFees.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 |
transactions.orderLineItems.marketplaceFees.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 |
transactions.orderLineItems.marketplaceFees.feeType | FeeTypeEnum | The enumeration value returned here indicates the type of fee that was deducted from the seller's payout. Occurrence: Conditional |
transactions.paymentsEntity | string | This string value indicates the entity that is processing the payment. Occurrence: Conditional |
transactions.payoutId | string | The unique identifier of the seller payout associated with the monetary transaction. This identifier is generated once eBay begins processing the payout for the corresponding order. This field will not be returned if eBay has not yet begun processing the payout for an order. Occurrence: Conditional |
transactions.references | array of Reference | This field contains reference information for the transaction fee. This includes an ID and the type of ID provided (such as item ID). Occurrence: Conditional |
transactions.references.referenceId | string | The identifier of the transaction as specified by the referenceType. For example, with a referenceType of item_id, the referenceId refers to a unique item. This item may have several NON_SALE_CHARGE transactions. Occurrence: Conditional |
transactions.references.referenceType | ReferenceTypeEnum | An enumeration value that identifies the transaction of the type associated with the referenceId. Occurrence: Conditional |
transactions.salesRecordReference | string | The Sales Record Number associated with a sales order. Sales Record Numbers are Selling Manager/Selling Manager Pro identifiers that are created at order checkout. Note: For all orders originating after February 1, 2020, a value of 0 will be returned in this field. The Sales Record Number field has also been removed from Seller Hub. Instead of salesRecordReference, depend on orderId instead as the identifier of the order. The salesRecordReference field has been scheduled for deprecation, and a date for when this field will no longer be returned at all will be announced soon. Occurrence: Always |
transactions.totalFeeBasisAmount | Amount | This amount is the total amount of the order before selling fees are deducted from the seller payout associated with the order. To determine the actual amount of the order that will be paid out through a seller payout, deduct the totalFeeAmount from the basePayoutAmount. Occurrence: Conditional |
transactions.totalFeeAmount | Amount | This amount is the total amount of selling fees paid for order. A breakdown of fees for each order line item can be found in the orderLineItems array. This field is even returned if it is 0.0 (no fees deducted from seller payout). Occurrence: Conditional |
transactions.transactionDate | string | This timestamp indicates when the monetary transaction (order purchase, buyer refund, seller credit) occurred. The following format is used: YYYY-MM-DDTHH:MM:SS.SSSZ . For example, 2015-08-04T19:09:02.768Z . Occurrence: Always |
transactions.transactionId | string | The unique identifier of the monetary transaction. A monetary transaction can be a sales order, an order refund to the buyer, a credit to the seller's account, a debit to the seller for the purchase of a shipping label, or a transaction where eBay recouped money from the seller if the seller lost a buyer-initiated payment dispute. Occurrence: Always |
transactions.transactionMemo | string | This field provides more details on a shipping label transaction, such as a purchase, a refund, or a price adjustment to the cost of the shipping label. This field is only returned if applicable/available. Currently, this field is only used for shipping label transactions, but it is possible that it will be used for other transaction types in the future. Occurrence: Conditional |
transactions.transactionStatus | TransactionStatusEnum | This enumeration value indicates the current status of the seller payout associated with the monetary transaction. See the TransactionStatusEnum type for more information on the different states. Occurrence: Always |
transactions.transactionType | TransactionTypeEnum | This enumeration value indicates whether the monetary transaction is a buyer's payment for an order, a refund to the buyer for a returned item or cancelled order, a credit issued by eBay to the seller's account, a payment dispute between the buyer and seller, or where eBay is billing the seller for an eBay shipping label or another charge (such as a refund to a buyer). Note that the shipping label functionality will initially only be available to a select number of sellers. 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 |
204 | No Content |
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. |
135003 | API_FINANCES | REQUEST | The value of pagination is invalid. |
135005 | API_FINANCES | REQUEST | The value of sorting is invalid. |
135006 | API_FINANCES | REQUEST | The value of transaction type filter is invalid. |
135007 | API_FINANCES | REQUEST | The value of transaction status filter is invalid. |
135008 | API_FINANCES | REQUEST | The value of transaction date filter is invalid. |
135009 | API_FINANCES | REQUEST | Transaction type filter is missing. |
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 All Transactions
Input
Output
20
(up to 20 payouts per page of the result set) and the offset value defaults to 0
(the first payout in the result set is shown first). Since the next field appears in the response, there are actually more than 20 monetary transactions to view, but the current page is only showing 20 since the limit value is 20
. The next field contains the full call URI to use to retrieve the next page of the result set.
Each monetary transaction is identified with its transactionId value. This transactionId value is auto-generated by eBay as soon as a buyer purchases an item, or if there is a commitment to buy (e.g., a winning bidder of an auction). The transactionType value will either be
SALE
, REFUND
, CREDIT
, or TRANSFER
. This particular response does not include any seller credits. If a payout has already been issued for a sale, the transactionStatus value will show PAYOUT
, and the payoutId value will identify the payout. If the transactionStatus value shows FUNDS_ON_HOLD
or FUNDS_PROCESSING
for a sale, you will not see a payoutId field for that sale.
Sample 2: Get Sales Within a Date Range
Input
SALE
, and one to filter within a date range. In this sample, the date range is between October 23 and November 9, 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
20
(up to 20 transactions per page of the result set) and the offset value defaults to 0
(the first transaction in the result set is shown first). Since only 16 successful sales transactions are returned, this response is showing all sales that occurred within the date range.
Each sales transaction is identified with its transactionId value. This transactionId value is auto-generated by eBay as soon as a buyer purchases an item, or if there is a commitment to buy (e.g., a winning bidder of an auction). For many of the sales transactions in this response, payouts have already been issued (the transactionStatus value shows
PAYOUT
, and the payoutId value identifies the payout. For other sales transactions, the transactionStatus value shows FUNDS_ON_HOLD
or FUNDS_PROCESSING
, which means the payout associated with the sales transaction has yet to occur.
Sample 3: Get Sales With Payment Holds
Input
SALE
, and one to filter by the transaction status of FUNDS_ON_HOLD
Below is the syntax to use for a non-date filter:
?filter=
filter_type:{
filter_value}
Output
Sample 4: Get Refunds for Specific Buyer
Input
REFUND
, and one to filter by the buyer's eBay user ID. For this particular call sample, the buyer's eBay user ID is rrpbuyer2
, so all refunds issued to this buyer by the are returned.
Below is the syntax to use for a non-date filter:
?filter=
filter_type:{
filter_value}
Output
4
in the total field. The seller has already been paid out for two of the sales transactions where the buyer will receive a refund, but the seller is still waiting for the payouts for the two other sales transactions.
Sample 5: Shipping Label Transactions
Input
SHIPPING_LABEL
.
Below is the syntax to use for a non-date filter:
?filter=
filter_type:{
filter_value}
Output
5
in the total field. The transactionMemo field gives more details on each shipping label transaction, and the lt;b>bookingEntry field value indicates whether it is charge (debit) or credit to the seller.
Sample 6: Get final value fees for an order
Input
03-00011-61743
.