GET/transaction
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.
The getTransactions method allows a seller to retrieve information about one or more of their monetary transactions.
Note: For a complete list of transaction types, refer to TransactionTypeEnum.
Numerous input filters are available which can be used individually or combined to refine the data that are returned. For example:
SALE
transactions for August 15, 2022;RETURN
transactions for the month of January, 2021;- Transactions currently in a
transactionStatus
equal toFUNDS_ON_HOLD
.
Pagination and sort query parameters are also provided that allow users to further control how monetary transactions are displayed 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
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
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 . 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 previous monetary transactions are returned:
Occurrence: Optional |
sort | array of SortField | By default, monetary transactions that match the input criteria are sorted in descending order according to the transaction date (i.e, most recent transactions returned first). To view transactions in ascending order instead (i.e., oldest transactions first), you would include the sort query parameter and set its value to transactionDate . Below is the proper syntax to use if filtering by a transaction date range in ascending order:https://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionDate:[2023-10-01T00:00:01.000Z..2023-10-12T00:00:01.000Z]&sort=transactionDate Transactions can only be sorted according to transaction date. 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 |
---|---|---|
X-EBAY-C-MARKETPLACE-ID | string | This 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/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 Occurrence: Always |
next | string | The getTransactions method URI to use if you wish to view the next page of the result set. 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 Occurrence: Always |
prev | string | The getTransactions method URI to use if you wish to view the previous page of the result set. 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.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 |
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. Occurrence: Conditional |
transactions.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 |
transactions.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 |
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. 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. 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 ( 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 Occurrence: Conditional |
transactions.buyer.username | string | The eBay user ID of the order's buyer. Occurrence: Always |
transactions.eBayCollectedTaxAmount | Amount | This is the amount of sales tax that has been collected by eBay for an order. Occurrence: Conditional |
transactions.eBayCollectedTaxAmount.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 |
transactions.eBayCollectedTaxAmount.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 |
transactions.eBayCollectedTaxAmount.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 |
transactions.eBayCollectedTaxAmount.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 |
transactions.eBayCollectedTaxAmount.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: Conditional |
transactions.eBayCollectedTaxAmount.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 |
transactions.eBayCollectedTaxAmount.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.feeJurisdiction | FeeJurisdiction | This container stores information about region-specific fees that are charged to sellers.
Occurrence: Conditional |
transactions.feeJurisdiction.regionName | string | String value that indicates the name of the region to which a region-specific fee applies. Occurrence: Conditional |
transactions.feeJurisdiction.regionType | RegionTypeEnum | The enumeration value returned here indicates the type of region that is collecting the corresponding fee. Occurrence: Conditional |
transactions.feeType | FeeTypeEnum | The enumeration value returned in this field indicates the type of fee that was deducted from the seller payout. 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.donations | array of Fee | The list of donations applied to the line item. Occurrence: Conditional |
transactions.orderLineItems.donations.amount | Amount | The amount of the fee. Occurrence: Conditional |
transactions.orderLineItems.donations.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 |
transactions.orderLineItems.donations.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 |
transactions.orderLineItems.donations.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 |
transactions.orderLineItems.donations.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 |
transactions.orderLineItems.donations.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: Conditional |
transactions.orderLineItems.donations.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 |
transactions.orderLineItems.donations.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.donations.feeJurisdiction | FeeJurisdiction | Indicates the specific jurisdiction for the fee that has been deducted from the seller payout. Occurrence: Conditional |
transactions.orderLineItems.donations.feeJurisdiction.regionName | string | String value that indicates the name of the region to which a region-specific fee applies. Occurrence: Conditional |
transactions.orderLineItems.donations.feeJurisdiction.regionType | RegionTypeEnum | The enumeration value returned here indicates the type of region that is collecting the corresponding fee. Occurrence: Conditional |
transactions.orderLineItems.donations.feeMemo | string | A description of the fee that was deducted from the seller payout. Occurrence: Conditional |
transactions.orderLineItems.donations.feeType | FeeTypeEnum | The enumeration value returned here indicates the type of fee that was deducted from the seller payout. Occurrence: Conditional |
transactions.orderLineItems.feeBasisAmount | Amount | This amount is the order's total amount and equals what the buyer has paid. This value includes transactions.amount, totalFeeAmount, eBayCollectedTaxAmount, and shipping charges (if any). 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. 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. Occurrence: Conditional |
transactions.orderLineItems.feeBasisAmount.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 |
transactions.orderLineItems.feeBasisAmount.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 |
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. 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. 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.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 |
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. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.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 |
transactions.orderLineItems.marketplaceFees.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 |
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. 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. 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.feeJurisdiction | FeeJurisdiction | Indicates the specific jurisdiction for the fee that has been deducted from the seller payout. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.feeJurisdiction.regionName | string | String value that indicates the name of the region to which a region-specific fee applies. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.feeJurisdiction.regionType | RegionTypeEnum | The enumeration value returned here indicates the type of region that is collecting the corresponding fee. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.feeMemo | string | A description of the fee that was deducted from the seller payout. Occurrence: Conditional |
transactions.orderLineItems.marketplaceFees.feeType | FeeTypeEnum | The enumeration value returned here indicates the type of fee that was deducted from the seller payout. Occurrence: Conditional |
transactions.paymentsEntity | string | This string value indicates the entity that is processing the payment. Occurrence: Conditional |
transactions.payoutDetails | PayoutDetails | This container provides the payout details for a split-payout case. This container is only returned for split-payout use cases. Occurrence: Conditional |
transactions.payoutDetails.payoutIds | array of string | This array indicates the list of true(actual) payout ids associated with a split payout. These values can be used as a path parameter for the getPayout method to retrieve details on the associated payouts. Occurrence: Conditional |
transactions.payoutDetails.payoutReference | string | This field contains the unique identifier for the Payout Reference. In split-payout cases, this is the unique identifier reference (not true payout). This field is only returned and will show the associated true(actual) payout id(s) when sellers in Mainland China enable split payouts between a Payoneer account and/or a bank account. This value can be used by the filter query parameter of the getPayouts method to get the monetary details of each true(actual) payout associated with the payoutReference. 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 Occurrence: Conditional |
transactions.references.referenceType | ReferenceTypeEnum | An enumeration value that identifies the reference 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. Occurrence: Always |
transactions.taxes | array of Tax | This array shows the tax type and amount applicable to the transaction. Occurrence: Conditional |
transactions.taxes.taxType | TaxTypeEnum | The enumeration value returned here indicates the type of tax. Occurrence: Conditional |
transactions.taxes.amount | Amount | Amount of tax. Occurrence: Conditional |
transactions.taxes.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 |
transactions.taxes.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 |
transactions.taxes.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 |
transactions.taxes.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 |
transactions.taxes.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: Conditional |
transactions.taxes.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 |
transactions.taxes.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.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. Occurrence: Conditional |
transactions.totalFeeAmount.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 |
transactions.totalFeeAmount.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 |
transactions.totalFeeAmount.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 |
transactions.totalFeeAmount.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 |
transactions.totalFeeAmount.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: Conditional |
transactions.totalFeeAmount.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 |
transactions.totalFeeAmount.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.totalFeeBasisAmount | Amount | This amount is the total amount for the order before selling fees are deducted from the seller payout associated with the order. Occurrence: Conditional |
transactions.totalFeeBasisAmount.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 |
transactions.totalFeeBasisAmount.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 |
transactions.totalFeeBasisAmount.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 |
transactions.totalFeeBasisAmount.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 |
transactions.totalFeeBasisAmount.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: Conditional |
transactions.totalFeeBasisAmount.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 |
transactions.totalFeeBasisAmount.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.transactionDate | string | This timestamp indicates when the monetary transaction (order purchase, buyer refund, seller credit) occurred. The following (UTC) format is used: 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 shipping label transactions and transactions where the funds are being held by eBay. For shipping label transactions, the transactionMemo gives details about a purchase, a refund, or a price adjustment to the cost of the shipping label. For on-hold transactions, the transactionMemo provides information on the reason for the hold or when the hold will be released (e.g., "Funds on hold. Estimated release on Jun 1"). Occurrence: Conditional |
transactions.transactionStatus | TransactionStatusEnum | This enumeration value indicates the current status of the seller payout associated with the monetary transaction. See the Occurrence: Always |
transactions.transactionType | TransactionTypeEnum | This enumeration value indicates the type of monetary transaction. Examples of monetary transactions include a buyer's payment for an order, a refund to the buyer for a returned item or cancelled order, or a credit issued by eBay to the seller's account. For a complete list of monetary transaction types within the Finances API, see the TransactionTypeEnum type. 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
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 All Transactions
This call sample retrieves all recent monetary transactions. No filters, no sorting, and no pagination parameters are used.
Input
Only the GET HTTP method and the endpoint are used. No filter parameters, no sorting, and no pagination query parameters are used.
GEThttps://apiz.ebay.com/sell/finances/v1/transaction
Output
The output returns details on 20 recent monetary transactions. Unless a sort query parameter is used, monetary transactions in a getTransactions response are sorted according to sale date in descending order (most recent sale first). Since no pagination query parameters were used, the limit value defaults to 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. If the transactionStatus value shows FUNDS_ON_HOLD
, the transactionMemo provides information on the reason for the hold and/or when the hold will be released (e.g., "Funds on hold. Estimated release on Jun 1").
Sample 2: Get Sales Within a Date Range
This call sample retrieves sales within a date range. Two filter parameters are used and configured to return sales within a stated date range.
Input
For this sample, two filter query parameters are used - one to filter by the transaction type of 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]
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SALE}&filter=transactionDate:[2018-10-23T00:00:01.000Z..2018-11-09T00:00:01.000Z]
Output
The output returns details on 16 sales that occurred within the specified date range. Since no pagination query parameters were used, the limit value defaults to 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. If the transactionStatus value shows FUNDS_ON_HOLD
, the transactionMemo provides information on the reason for the hold or when the hold will be released (e.g., "Funds on hold. Estimated release on Jun 1").
Sample 3: Get Sales With Payment Holds
This call sample retrieves sales with payment holds. Two filter parameters are used and configured to return sales with payment holds.
Input
For this sample, two filter query parameters are used - one to filter by the transaction type of 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}
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SALE}&filter=transactionStatus:{FUNDS_ON_HOLD}
Output
The output indicates that there are only two sales transactions where payout funds are on hold. The transactionMemo field gives more details on the reason for the hold or when the hold will be released. To get more information on payment holds, including the expected fund release date, the user can call getOrder.
Sample 4: Get Refunds for Specific Buyer
This call sample gets refunds for a specific buyer. Two filter parameters are used and configured to return refunds issued to a specific buyer.
Input
For this sample, two filter query parameters are used: one to filter by the transaction type of REFUND
, and one to filter by the buyer's eBay user ID. For this particular call sample, the buyer's eBay user ID is r********2
, 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}
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{REFUND}&filter=buyerUsername:{r********2}
Output
A total of four refunds to the buyer are part of the result set, as indicated by a value of 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
This call sample shows shipping label transactions, including a purchase of a shipping label, a refund for a shipping label, and a price adjustment for cost of shipping label.
Input
For this sample, a transactionType filter is used to retrieve only shipping label transactions. The value of the transactionType filter is set to SHIPPING_LABEL
.
Below is the syntax to use for a non-date filter:
?filter=
filter_type:{
filter_value}
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SHIPPING_LABEL}
Output
A total of five shipping label transactions are part of the result set, as indicated by a value of 5
in the total field. The transactionMemo field gives more details on each shipping label transaction, and the bookingEntry field value indicates whether it is charge (debit) or credit to the seller.
Sample 6: Get final value fees for an order
This call sample shows final value fees for a specific order. An orderId value is used as a filter, so only transactions related to that sales order are returned.
Input
For this sample, orderId is include as a filter, and the seller wishes to retrieve all transactions related to the order ID 03-00011-61743
.
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=orderId:{0********3}
Output
Only one SALE transaction is returned for the order. The totalFeeBasisAmount is the total amount of the order used to calculate the seller's final value fees for the order. The total amount of seller fees deducted from a seller payout associated with the order is shown in the totalFeeAmount field. Line item-level information about seller fees are returned in the orderLineItems array. This particular order contains just one line item.
Sample 7: Get Transactions associated with Split Payout
This call sample retrieves all recent monetary transactions for a seller associated with a split payout. Split payout is only available to sellers in mainland China.
Input
Only the GET HTTP method and the endpoint are used. The payoutReference filter is used in this sample to return information on every monetary transaction associated with the specified split payout.
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=payoutReference:{5********5}
Output
One transaction is returned as part of the result set, as indicated by the value of 1
in the total field. In addition to the usual information returned in a getTransactions call, calls made by sellers in mainland China using split payout return the payoutDetails container. This container includes the payoutIds and the payoutReference associated with a transaction. The payoutReference is the unique identifier associated with the true(actual) payout ids. The payoutIds array indicates the list of true(actual) payout ids associated with a split payout.
Sample 8: Get charitable donations against a sale
This call sample retrieves charitable donations against a sale.
Input
If the transaction has charitable donation against a sale, it is returned.
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SALE}
Output
The output returns the amount of charitable donations against a sale.
The sales transaction returned in the response is identified with its transactionId value. As indicated in the donations array, an amount of $10 went toward a charitable donation, and this amount was deducted from the seller's total payout from this sale.
Sample 9: Get shipping label transactions with tax
This call sample retrieves transactions to show shipping label transactions with tax.
Input
If the transaction has shipping label with tax, it is returned.
GEThttps://apiz.ebay.com/sell/finances/v1/transaction?filter=transactionType:{SHIPPING_LABEL}
Output
The output returns details of transactions to show tax that is applied to purchased shipping labels.
The shipping label transaction in the response shows that $0.87 tax was charged against the purchase of the shipping label.